Troubleshooting

How-to. Common symptoms and what to check.

Symptom	Check
401 from the MCP server	The header must be exactly Authorization: Bearer <AGENTBOX_MCP_TOKEN>. Re-run claude mcp add after changing the token.
repo_path must be inside ...	Put the repo under AGENTBOX_REPOS_ROOT, or change it in .env and run docker compose up -d.
error: ... launcher	docker logs agentbox-launcher. Is DOCKER_GID right? Does $AGENTBOX_DATA/run/launcher.sock exist?
vLLM model "exited during load"	journalctl -t agentbox-<model-id>. Usually memory (--gpu-memory-utilization, --kv-cache-memory-bytes) or an image or flag mismatch.
Long wait_seconds	First use of a vLLM model (5–7 min load), an Ollama pull, or waiting for agents on the other GPU family to finish.
status: timeout	The agent hit timeout_minutes. The diff is still collected, so check what it got done. Split the task or point it at the right files.
harness_error with an empty report	The model server died mid-run (look for OOM in journalctl -k), or the model emitted malformed tool calls. Check delegations.jsonl and the backend logs.
Agent says pytest is missing	Pass python_env (build it with make_venv.sh). The sandbox can't pip install.
Gateway 403 ... budget exhausted	The task burned through its token budget (20M by default), usually a loop. Tighten the spec.
error: ... llm-bridge / ... is not set in secrets.env	Add the key to secrets.env, then docker compose up -d. docker logs llm-bridge shows upstream errors.
run_checks says pytest is missing	Pass python_env (the same venv as the delegation).
agentbox-launcher exits at startup with a runtime error	Install the runtime, or register runsc with --host-uds=open (sudo runsc install -- --host-uds=open && sudo systemctl reload docker), or unset AGENTBOX_AGENT_RUNTIME. docker logs agentbox-launcher shows the exact fix.
cleanup_delegation can't delete files	The workspace is still owned by the agent uid. Calling cleanup_delegation again asks the launcher to hand it back first.

Logs:

• delegations: $AGENTBOX_DATA/logs/delegations.jsonl
• MCP server: docker logs agentbox
• launcher: docker logs agentbox-launcher
• vLLM: journalctl -t agentbox-<model>
• Ollama: docker logs ollama
• llm-bridge: docker logs llm-bridge