LOCAL-FIRST IMAGE INTELLIGENCE

Extensible local-first framework for indexing and orchestrating AI image assets.

Documentation • Releases • Installation • Container • Architecture • Build • Discord

Picteus is a local-first desktop and server platform designed to catalog, inspect, annotate, and orchestrate AI-generated image assets. It provides an extensible backbone that bridges creative workflows with local and remote machine learning runtimes, backed by structured and vector persistence layers.

Full documentation, manuals, and technical specifications are available at picteus.github.io/picteus:

• Installation and setup: hardware requirements, OS packages, initial startup sequences, and troubleshooting ;
• User manual: image indexing, faceted search, tag management, vector similarity search, and container deployment ;
• Extensions guide: authoring extensions using Python and TypeScript SDKs, manifest schema specifications, and Model Context Protocol (MCP) integrations ;
• Developer documentation: multi-component architecture, build processes, and continuous integration workflows.

Pre-packaged desktop binaries are distributed via the GitHub Releases page under the "Assets" section:

• Supported operating systems: Windows x64 and macOS ARM 64 — Apple Silicon — with Linux and Windows ARM 64 on the roadmap ;
• Hardware baseline: at least a 4-core CPU, a dedicated GPU for local inference models, 3 GB of free disk space, and 2 GB of available RAM ;
• Installation steps: double-click the .exe installer on Windows, or unpack the .app bundle into /Applications on macOS.

For complete installation details and configuration flags, consult the installation guide.

Picteus is also distributed as a container image for server deployments and headless evaluation:

# Create a persistent volume for internal runtime data
docker volume create picteus

# Start the Picteus container
docker run -d \
  --name picteus \
  -p 3001:3001 \
  -v picteus:/app/internal \
  -v /path/to/host/data:/app/external \
  -v /path/to/host/images:/app/files \
  -e filesMountPath=/path/to/host/images \
  koppasoft/picteus:latest

Once running, access the web interface and REST API at http://localhost:3001.

For complete volume mount details, Docker Compose definitions, and SSL configuration, read the container documentation.

Picteus connects to local engines and remote services through isolated extension runtimes:

• Local generation and inference: ComfyUI, Automatic1111, Ollama, and local Stable Diffusion upscalers ;
• Cloud providers and models: Anthropic Claude, Google Gemini, Midjourney, and Replicate ;
• Provenance and transformations: C2PA content credentials, Bria background removal, and color embeddings ;
• Agentic interoperability: Model Context Protocol (MCP) server integration, exposing Picteus tools and image search to AI agents.

For developer guides on authoring custom integrations, consult the extensions guide.

Picteus is structured across six primary components:

1. shared: compound libraries providing shared TypeScript models, back-end foundations, front-end helpers, and the specification-factory code emitters ;
2. back-end: NestJS and Node.js server exposing an OpenAPI v3.1 REST API, orchestrating extension runtimes and managing local persistence ;
3. extensions/sdk: official Python and TypeScript SDKs for developing decoupled plugins ;
4. extensions/instances: built-in extensions providing local machine learning model execution, third-party integrations, and MCP endpoints ;
5. front-end: React single-page interface leveraging Mantine UI for interactive exploration and asset management ;
6. electron: host shell embedding the front-end and back-end into a native desktop application.

Persistence relies locally on SQLite for relational metadata and generation parameters, and Chroma DB for high-dimensional vector embeddings.

For detailed component interaction diagrams and specifications, refer to the architecture documentation.

• Node.js: v22.7.1+ with npm ;
• Python: v3.11+ for building Python extension modules ;
• Java: v17+ required in PATH for generating OpenAPI client contracts ;
• Docker: Required when assembling the server container image.

Install root dependencies, link internal workspaces, and compile all artifacts:

# Install root package dependencies
npm install

# Resolve internal submodule dependencies across shared and back-end components
npm run prerequisites

# Build all components and extension bundles
npm run build

Compiled output is assembled under the build/ directory — symlinked to electron/build/. To clean build artifacts or reset working directories:

# Deletes compiled binaries and bundles
npm run clean

# Restores the repository to a clean git checkout
npm run reset

For sub-package workflows, environment variables, and Docker container packaging, read the build guide.

Contributors and maintainers are available on Discord to answer questions, discuss features, and collect feedback:

• Discord: Join the discussion on the Picteus Discord server — server ID 1549384585920385034 ;
• GitHub Issues: Report defects or submit technical enhancement proposals on GitHub Issues.

Picteus is maintained by engineers passionate about generative workflows and asset organization. To understand the design rationale, target audiences, and project philosophy, read the disclaimer.

This project is licensed under the terms of the GNU Affero General Public License v3.0. Refer to LICENSE for details.