Skip to content

docker-setup.md

Latest commit

 

History

History
157 lines (123 loc) · 6.94 KB

docker-setup.md

File metadata and controls

157 lines (123 loc) · 6.94 KB
Raw

Docker setup

The Compose definition is src/docker-compose.yml. It builds the agent, sandbox, and transcription images from sibling directories under src/. Tracked defaults and templates are under src/config/; mutable deployment configuration and runtime state are stored in the repository's ignored data/ directory.

Run setup first, then use the root Compose environment file:

./run.sh
docker compose --env-file data/.env up -d --build

Setup records the absolute Compose file list in data/.env, including the generated credentials overlay. Keep data/.compose-secrets.yaml present and do not replace the setup-generated value. Rerun setup after moving the checkout to refresh absolute Compose and sandbox mount paths. To inspect services:

docker compose --env-file data/.env ps
docker compose --env-file data/.env logs --tail=100 task-agent

For a custom Compose override, explicit -f options replace COMPOSE_FILE. Include -f src/docker-compose.yml -f data/.compose-secrets.yaml before your override file so the base services and credential mounts are retained.

Troubleshooting local administration

If ./run.sh fails while opening, check Docker in the same terminal:

docker info
docker version
docker context ls

On macOS, open Docker Desktop (or start your chosen runtime), wait for it to be ready, and retry. A context selects a particular daemon; a different context can have different images and volumes. Check DOCKER_HOST and DOCKER_CONTEXT if the selected endpoint is unexpected. Sudo normally is not needed for Docker Desktop and will not fix a stopped runtime.

Docker-volume credentials must be read before the home screen can open. If their volume is missing, select the original daemon or restore the volume backup; do not create an empty replacement. If Docker reports a registry credential-helper failure, repair the runtime's helper installation/PATH, unlock the macOS keychain, and renew docker login if necessary. Starting the credential helper container may need to pull python:3.12-slim.

The interface reports recognized error categories, the failed operation, and its exit status without displaying raw Docker output. For Compose configuration errors, run docker compose --env-file data/.env config --quiet from the repository root. For unrecognized failures, inspect the failing operation locally. Docker output can contain credentials and private paths: review and redact it before sharing. Neither diagnostics nor retry recreate missing credential volumes or reset application data.

Services and profiles

The stack includes PostgreSQL, agent workers, Ollama, ClamAV, the sandbox broker, and one-shot setup helpers. Email intake, Telegram, and voice transcription are enabled with their corresponding Compose profiles when selected during setup. See architecture for role summaries. No application ports are published, and the current stack has no api profile, browser dashboard, or management API.

Networks and boundaries

Compose separates database, model, malware-scanning, transcription, and sandbox control traffic into scoped networks. Services needing external providers also use egress. PostgreSQL is not attached to egress. The sandbox broker uses authenticated HTTPS on its internal control network; command containers are created per request on separate internal networks and reach the internet only through a per-run HTTPS egress proxy restricted to approved hosts (SANDBOX_EGRESS_MODE=open in data/.env restores direct access). See sandbox network isolation.

Each command container receives the shared workspace, not application credentials or the Docker socket. The broker itself requires the Docker socket to create and remove command containers and therefore has daemon-level authority. This remains a significant host trust boundary; see security.

Persistent mounts

Compose keeps host state under data/, including:

  • data/postgres/ — database.
  • data/share/ — shared workspace.
  • data/private/ — artifacts and TLS files.
  • data/ollama/ — embedding model cache.
  • data/clamav/ — malware signatures.
  • data/config/agent.yaml — runtime defaults (copied from tracked defaults if absent).
  • data/config/AGENT.md — runtime prompt.

data/config/ is mounted read-only at /app/config in application containers. Setup preserves an existing data/config/agent.yaml; rebuilding images does not refresh it from src/config/agent.yaml.

Documentation is bundled in the application image at /app/docs for the help_search and help_topic tools. It is not mounted from the host or copied into workspace storage, the sandbox broker or per-command containers. Rebuild the application image to update help content.

By default, credential source files are protected plaintext files in data/.secrets/; the generated data/.compose-secrets.yaml grants read-only mounts only to authorized services. Setup can instead move credentials to a dedicated external Docker volume with service-specific mounts. Neither store is encrypted; retain the overlay and data/.secrets/state.json in either mode. See credential storage. The sandbox broker's certificate/key/token are staged by sandbox-init in a protected Docker volume; command containers receive no credentials.

Sandbox defaults

The Compose default uses container isolation, a read-only broker filesystem, dropped broker capabilities, no-new-privileges, and CPU, memory, and PID limits for command containers. Run containers drop NET_RAW; the Docker socket is mounted only in the broker. The broker's privileges and residual container-escape risk are described in security. Disabling AGENT_SANDBOX_ENABLED disables the agent's command tool only; it does not remove the broker service or its Docker socket mount from Compose.

Maintenance

When upgrading to version-bound script permissions, save setup again before rebuilding so revoke-only credentials and service-specific secret grants are generated. A container restart alone does not activate the change. See the upgrade and acceptance checklist.

Rebuild and recreate after changing application source:

docker compose --env-file data/.env up -d --build

For environment-file changes, recreate containers to reload their environment (a restart alone is insufficient):

docker compose --env-file data/.env up -d --force-recreate

Stop without deleting persistent bind mounts:

docker compose --env-file data/.env down

Avoid down --volumes unless intentionally deleting managed volumes, including the transcription model/runtime and sandbox credential runtime volumes. Back up data/ and protect the copies as confidential. If enabled, back up the external credential volume separately; down --volumes does not delete that external volume, but explicit removal or volume pruning can.