Start with the doctor

podman compose exec agent-server python -m disco.agent_server.doctor
# docker compose exec agent-server python -m disco.agent_server.doctor

PASS config        build v0.2.0 (3f9c1a2) (image); 14 DISCO_* variables set
PASS agent-server  ok, version v0.2.0 (3f9c1a2)
PASS app-server    ok, version v0.2.0 (3f9c1a2)
FAIL sandbox       podman: podman sandbox host unix:///var/run/docker.sock unreachable: [Errno 2] No such file or directory
PASS data disk     41.2 GB free at /data
PASS database      /data/disco.db: quick_check ok, 18342 events, 61 MB
PASS secret key    DISCO_SECRET_KEY set
PASS driver model  config PASS | completion PASS | tool-calling PASS

1 check(s) FAILED

The process exits non-zero when a check fails. --no-model skips the driver-model check (it calls your model once); --app-url points the app-server check at a split deployment; --bundle PATH also writes the support bundle.

Reading logs

podman compose logs -f agent-server      # the loop, providers, sandbox
podman compose logs -f app-server        # settings, auth, pairing, quotas
podman compose logs --since 10m frontend

DISCO_LOG_LEVEL=DEBUG in .env raises both Python servers; DISCO_LOG_JSON=1 emits one JSON object per line. Logs are bounded at 20 MB per service and are gone after compose down, so copy what you need first.

Common failures, by message

You see	Cause	Fix
podman sandbox host unix:///var/run/docker.sock unreachable	The rootless Podman socket is not enabled or not mounted	systemctl --user enable --now podman.socket, export DISCO_SANDBOX_SOCKET=$XDG_RUNTIME_DIR/podman/podman.sock, podman compose up -d again
image "disco-sandbox:base" is not present on the host	The sandbox-image service did not run	podman compose up -d sandbox-image; for a source build add -f compose.build.yaml --build
Error: invalid port format	podman-compose 1.3.x cannot expand the compose file’s defaults	Install docker-compose (Compose v2) as the provider
Provider Test fails connecting to host.docker.internal	Rootless Docker has no route from that name back to the host	Use the host’s LAN IP and bind the model server to 0.0.0.0
The browser asks for a pairing token	The UI is opened from another machine, or a proxy sits in front	podman compose exec app-server python -m disco.app_server.pairing_cli
A Build never uses tools; doctor says tool-calling FAIL	The driver model cannot emit tool calls	Pick a model that does; the doctor quotes the provider’s error
agent-server health degraded with store: error	The database is unreadable or the volume is full	The doctor’s disk and database lines say which; free space or restore a backup
A run sits at RUNNING for a long time	The model is slow, or it is verifying repeatedly	The run’s Checks section shows what it re-ran; DISCO_INSPECT=1 gives per-turn model timing
Settings say a key is saved but runs fail auth	The encrypted-settings key changed between restarts	Set DISCO_SECRET_KEY; the doctor warns when none is set

Which build am I running?

curl -s http://127.0.0.1:8000/health | python3 -m json.tool      # agent-server
curl -s http://127.0.0.1:8800/api/health | python3 -m json.tool  # app-server

Both return version (tag and commit) and build. Release images carry both; a local build from a checkout says unknown unless you export DISCO_BUILD_TAG and DISCO_BUILD_COMMIT first.

Reference: docs/troubleshooting.md in the repository is the versioned copy of this page.