Installation

How-to. Install agentbox on a Linux GPU machine.

Requirements

• Linux with Docker Engine ≥ 27 and Docker Compose v2 (with gpus: support)
• NVIDIA GPU + NVIDIA Container Toolkit (docker run --rm --gpus all ubuntu nvidia-smi works)
• uv and Python 3
• Claude Code for the planner
• Disk: about 1 GB for images, plus model weights

Steps

1. Clone and configure:

   git clone https://github.com/Adithya-Rajendran/agentbox && cd agentbox
   scripts/setup.sh

   To use other paths, set them on the setup command line: AGENTBOX_DATA=/data/agentbox AGENTBOX_REPOS_ROOT=~/code OLLAMA_MODELS_DIR=/data/ollama scripts/setup.sh. AGENTBOX_REPOS_ROOT (default: your home) is only an allowlist for the folders Claude may pass in. Nothing is mounted from it. setup.sh is safe to re-run. It never overwrites .env, secrets.env or config/models.yaml.
2. Review config/models.yaml. The shipped models target a 128 GB unified-memory GPU; see Add a local model to adapt them.
3. Build and start:

   docker compose --profile build build
   docker compose up -d

4. Verify:

   scripts/smoke-test.sh                    # default model (Ollama)
   scripts/smoke-test.sh <vllm-model-id>    # optional: a vLLM model too

5. Register the MCP server with Claude Code and install the planner skill:

   claude mcp add --transport http local-agents http://127.0.0.1:8765/mcp --scope user \
     --header "Authorization: Bearer $(grep ^AGENTBOX_MCP_TOKEN= .env | cut -d= -f2)"
   ln -s "$PWD/skills/local-agent-delegation" ~/.claude/skills/

   Delegations can run longer than Claude Code's default MCP tool timeout. Set export MCP_TOOL_TIMEOUT=7200000 in the environment Claude Code runs in.

Recommended: install gVisor before step 1. Then setup.sh enables it automatically. It's optional: without it, agents share the host kernel (runc). See Run agents under gVisor. setup.sh prints which runtime will be used.