Your First Delegation

Tutorial. In about 20 minutes you will install agentbox, check that the sandbox works, delegate a real bug fix to a local model, verify it inside the sandbox, and merge it. No prior agentbox knowledge is needed.

You'll need:

• a Linux machine with Docker, an NVIDIA GPU and the NVIDIA Container Toolkit;
• uv;
• Claude Code.

0. (Recommended) Install gVisor

Follow steps 1–2 of Run agents under gVisor first. Then setup.sh will run your agents under gVisor's user-space kernel automatically. You can skip this and add it later.

1. Install and start agentbox

git clone https://github.com/Adithya-Rajendran/agentbox ~/agentbox && cd ~/agentbox
scripts/setup.sh
docker compose --profile build build
docker compose up -d
docker compose ps

setup.sh writes .env with your user ids and fresh tokens, and creates config/models.yaml from the example. docker compose ps should show ollama, agentbox, agentbox-launcher and llm-bridge as running.

2. Prove the sandbox works

scripts/smoke-test.sh

The first run downloads the default Ollama model (~25 GB). The script delegates a one-line bug fix, then checks that the result is right and that the agent ran with no network, a read-only root, no capabilities and uid 64000. It also verifies the branch with run_checks. Expect every line to say PASS.

3. Connect Claude Code

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/

4. Make something to fix

mkdir -p ~/Projects/tutorial && cd ~/Projects/tutorial && git init -q
cat > slug.py <<'PY'
def slugify(title: str) -> str:
    return title.lower().replace(" ", "-")
PY
cat > test_slug.py <<'PY'
from slug import slugify

def test_basic():
    assert slugify("Hello World") == "hello-world"
PY
git add -A && git commit -qm "slugify"

(Claude passes this folder to agentbox as repo_path. Only this one repo is touched. Any folder under AGENTBOX_REPOS_ROOT, your home by default, is allowed.)

5. Delegate

In that directory, start claude and ask:

slugify(" Hello, World! ") should return "hello-world": strip leading/trailing whitespace, drop punctuation, and collapse runs of spaces into one dash. Plan it, then delegate the implementation to the local model with delegate_task, and verify the result with run_checks before merging.

What you'll see:

1. Claude writes a spec, using the delegation skill: the goal, the cases to cover, where to look, and how to verify.
2. delegate_task runs for a minute or two. It returns a branch agent/<id>, a diff, and a report labelled as untrusted.
3. Claude reads the diff, then calls run_checks with python3 -m pytest -q (or a plain python3 -c … check if pytest isn't installed). The tests run on the branch, inside a sandbox.
4. If they pass, Claude merges with git merge --no-ff agent/<id> and calls cleanup_delegation.

6. Look around

git log --oneline --graph          # the agent's commit, merged
tail -1 ~/.local/share/agentbox/logs/delegations.jsonl | python3 -m json.tool

The log line records the model, turns, wait and wall time, tokens and diff size.

Where next

• Delegate real work: Write a spec a local model gets right and Prepare a Python environment.
• Use a bigger model: Add a local model or Connect remote APIs.
• Understand what just happened: Life of a delegation.