Cogtrix Docker deployment

Run Cogtrix in a container — useful for unattended assistant mode, CI workflows, or just keeping your local Python clean.

Build the image

git clone https://github.com/NorthlandPositronics/Cogtrix.git
cd Cogtrix
docker build -t cogtrix:next -f docker/Dockerfile .

The image is Python 3.13-alpine-based with uv and all runtime dependencies. Build takes ~2–3 minutes the first time.

Run interactively

docker run --network host -it --rm \
  -v "$HOME/.cogtrix.yml:/app/.cogtrix.yml:ro" \
  -v cogtrix-data:/data \
  cogtrix:next

Notes:

• --network host lets Cogtrix reach Ollama on localhost:11434.
• The config is mounted read-only at /app/.cogtrix.yml.
• A named volume cogtrix-data persists session history, memory, and the vector DB.

Run in API mode

Append api to the command:

docker run --network host -it --rm \
  -e COGTRIX_JWT_SECRET="$(openssl rand -hex 32)" \
  -v "$HOME/.cogtrix.yml:/app/.cogtrix.yml:ro" \
  -v cogtrix-data:/data \
  cogtrix:next \
  api --debug

The docker entrypoint detects api and starts the FastAPI server (python -m src.api) instead of the interactive CLI. Listens on port 8000 inside the container.

docker-compose

For a persistent setup, docker/docker-compose.yml in the Cogtrix repo provides a working compose file:

services:
  cogtrix:
    image: cogtrix:next
    network_mode: host
    environment:
      - COGTRIX_JWT_SECRET=${COGTRIX_JWT_SECRET}
    volumes:
      - ${HOME}/.cogtrix.yml:/app/.cogtrix.yml:ro
      - cogtrix-data:/data
    command: api

volumes:
  cogtrix-data:

Then:

docker compose up -d

Healthcheck

The image ships with a healthcheck that probes /api/v1/health/ready in API mode and skips the probe in CLI mode (via a sentinel at /run/cogtrix/api-mode). Container orchestrators (k8s, Nomad, etc.) can rely on the standard Docker healthcheck.

Custom workspace + sandboxing

For agent runs that should be confined to a specific directory:

docker run --network host -it --rm \
  -v "$PWD/workspace:/workspace:rw" \
  cogtrix:next \
  --allow-write-path /workspace \
  --allow-read-path /workspace \
  -y \
  --prompt "Refactor parser.py and run the tests"

Combined with -y, this is the standard pattern for unattended runs.

Volume layout

/data/ is the canonical data root inside the container. The entrypoint creates these subdirectories on startup:

/data/
├── history/      session message history
├── knowledge/    RAG document store
├── vectordb/     embedded vector DB
├── api/uploads/  REST upload staging
├── assistant/    assistant-mode state (campaigns, contacts)
├── workflows/    workflow definitions and bindings
├── output/       agent file writes
├── log/          rotated log files
└── documents/    user-uploaded docs

Mount as a single volume to persist everything across container restarts.