Docker Compose

Local development stack

The checked-in local-development stack lives at docker-compose.yml in the q15 repo and uses templates under deploy/compose/.

Interface

File	Purpose
deploy/compose/agent-config.yaml	Structured agent config
deploy/compose/proxy-policy.yaml	Structured proxy policy
deploy/compose/secrets/	Local Docker secret files (from *.example templates)
deploy/compose/auth/	Local OpenAI auth state (from auth.json.example)

1. Initialize secrets

   make compose-secrets-init

2. Edit secret files under deploy/compose/secrets/ (remove .example suffix)
3. Edit auth at deploy/compose/auth/auth.json
4. Start the stack

   make compose-up

Local development notes

The local-development stack keeps local source builds enabled with build:, tags them with canonical GHCR names on :main, and uses named volumes for /workspace, /memory, /skills, and /nix.

Image-first deployment

For production, use the image-first Compose example at deploy/compose/docker-compose.image-first.yml:

make compose-secrets-init
Q15_IMAGE_TAG=sha-<short-sha> docker compose -f deploy/compose/docker-compose.image-first.yml up -d

The image-first example:

• Uses image: only (no local builds)
• Requires Q15_IMAGE_TAG applied to all three services
• Mounts persistent named volumes for all required paths
• Mounts config, policy, and auth at the exact runtime paths the binaries expect

Persistent volumes

Volume	Mount	Purpose
q15_workspace	/workspace	Durable project tree
q15_memory	/memory	Agent memory
q15_skills	/skills	Skill artifacts
q15_exec_nix_store	/nix	Nix store (keeps packages warm across sessions)
q15_qdrant_storage	Qdrant storage	Embedding vectors (when enabled)

Caution

An empty bind mount at /nix would hide the image-provided shell and nix installation. Use a Docker named volume instead, which preserves the image’s built-in bootstrap on first use via copy-up behavior.