Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• DEPLOYMENT.md
• README.md
• src/setup/wizard.ts
• design/infrastructure.md (Referenced via CLAUDE.md architecture section)
• CONTRIBUTING.md
• scripts/dev-infra.ts

Cogmo is a self-hosted personal agent runtime distributed as a single Node.js process within a Docker container. It is designed for single technical users to run on infrastructure they control, providing modularity with persistent memory and self-evolution capabilities.

The deployment involves orchestrating a core container that communicates with several required infrastructure components, including PostgreSQL with pgvector, Redis, Inngest, and the Hindsight memory server. Configuration is handled primarily through environment variables and a guided interactive setup wizard that encrypts sensitive credentials.

Sources: README.md:14-16, DEPLOYMENT.md:3-5, CLAUDE.md:1-5

Infrastructure Requirements

Cogmo requires a suite of supporting services to function. While it is distributed as a single container, it relies on externalized state and orchestration.

Component	Version	Purpose
PostgreSQL	18 (recommended)	Application state and vector storage (via pgvector). Native uuidv7() support in PG 18 is preferred.
Redis	7+	Inngest queue and state management.
Inngest	Latest	Event-driven durable execution and scheduling.
Hindsight	Latest-slim	Memory server providing vector search capabilities.
Docker	Latest	Runtime for pulling and executing the Cogmo image.

Sources: DEPLOYMENT.md:7-17, README.md:21-27

Component Relationship Diagram

The following diagram illustrates how the Cogmo runtime interacts with its mandatory infrastructure dependencies.

Deployment Process

The deployment follows a three-stage bootstrap sequence: key generation, interactive setup, and long-running service execution.

1. Key Generation

Cogmo uses a 32-byte base64 master key to encrypt credentials at rest using AES-256-GCM. This must be generated before the setup wizard is run.

docker run --rm ghcr.io/iskhakovt/cogmo:<version> gen-key

Sources: DEPLOYMENT.md:301-306, README.md:52-54

2. Setup Wizard

The setup command launches an interactive TUI (using @clack/prompts) that guides the user through provider configuration and validates credentials live.

3. Service Execution

Once configured, the agent is started using the serve command. This connects to Inngest and initializes configured channel adapters like Telegram.

docker run -d \
  -e DATABASE_URL=... \
  -e COGMO_MASTER_KEY=... \
  -p 9090:9090 \
  ghcr.io/iskhakovt/cogmo:<version> serve

Sources: DEPLOYMENT.md:325-334, README.md:70-78

Configuration Reference

Required Environment Variables

These variables must be provided for the container to reach its dependencies.

Variable	Description
DATABASE_URL	Postgres connection string. Supports DATABASE_URL_FILE for Docker secrets.
COGMO_MASTER_KEY	32-byte base64 key for AES-256-GCM encryption. Supports _FILE convention.
HINDSIGHT_URL	URL for the Hindsight memory server.
INNGEST_BASE_URL	URL for the Inngest server.

Sources: DEPLOYMENT.md:113-122, src/env.ts (as referenced in DEPLOYMENT.md)

Persistent State Volumes

For production deployments, the following paths within the container should be bind-mounted to host directories to ensure data persistence.

Container Path	Ownership	Importance
/var/lib/cogmo/skills	UID 1000	Critical: Authoritative git repo for all registered skills.
/var/lib/cogmo/repos	UID 1000	Cached git clones of external repositories.
/run/cogmo/sockets	UID 1000	Ephemeral Docker proxy sockets for sandbox tasks.

Sources: DEPLOYMENT.md:52-65, DEPLOYMENT.md:73-77

Observability

Cogmo supports OpenTelemetry (OTel) for traces, metrics, and logs. This is opt-in and requires setting the OTEL_EXPORTER_OTLP_ENDPOINT.

Telemetry Architecture

When OTLP is enabled, Cogmo exports data via HTTP/protobuf. Traces are automatically correlated with Inngest function runs.

Key Metrics and Spans:

• Traces: Spans for chat (LLM calls), tool.execute, and memory.recall.
• Metrics: cogmo.llm.tokens (labeled by model/provider) and cogmo.agent.iterations.
• Log Correlation: Pino logs include trace_id for stitching with spans in systems like Grafana.

Sources: DEPLOYMENT.md:354-385, DEPLOYMENT.md:434-445

Development Infrastructure

For local development, Cogmo provides a script to boot a complete local environment using testcontainers. This avoids the need for a manual docker-compose.yml.

Workflow:

1. pnpm dev:infra: Starts Postgres, Redis, Inngest, and Hindsight.
2. Applies database migrations automatically.
3. Spawns the app in watch mode using tsx.
4. Persists a local dev master key in .dev/master-key.

Sources: scripts/dev-infra.ts:18-35, scripts/dev-infra.ts:63-75, CONTRIBUTING.md:18-22

Summary

Cogmo deployment requires a stable infrastructure stack centered around PostgreSQL and Inngest. By utilizing the built-in setup wizard, sensitive API keys for LLMs and messaging platforms are securely stored in the database. Production readiness is achieved by ensuring persistent volumes for the skills library and configuring OTel-based observability to monitor the agentic loop's performance and token usage.

Sources: DEPLOYMENT.md:1-5, README.md:105-110