AI Agent Sandbox

Your AI agent needs a machine it can break. Not your laptop — a disposable server where it can install packages, modify system configs, and rm -rf whatever it wants. When it's done, the fire goes out.

The pattern

Every agent interaction follows the same three steps:

# 1. Forge — agent gets its own server
RESULT=$(gibil create --name agent-task \
  --repo https://github.com/you/project \
  --ttl 20 --json)

# 2. Use — agent works on the server
gibil run agent-task "cd /root/project && pnpm install && pnpm test" --json

# 3. Burn — clean up
gibil destroy agent-task --json

The --json flag on every command gives your agent structured data — no stdout parsing, no regex.

Waiting for readiness

After gibil create, the VM boots and runs cloud-init (installs runtime, clones repo, runs tasks). Your agent should poll for readiness:

# Poll until infra is ready
gibil run agent-task "test -f /root/.gibil-ready" --json
# exit_code 0 = repo cloned, runtime installed

# Poll until all tasks complete
gibil run agent-task "test -f /root/.gibil-tasks-done" --json
# exit_code 0 = pnpm install, build, test all ran

If tasks fail, .gibil-tasks-failed is created instead of .gibil-tasks-done. Check for both.

Parallel agents

Spin up multiple VMs for independent tasks. Each is fully isolated — different repos, different branches, no conflicts:

gibil create --name task-1 --repo https://github.com/you/project --ttl 20 --json &
gibil create --name task-2 --repo https://github.com/you/project --ttl 20 --json &
gibil create --name task-3 --repo https://github.com/you/project --ttl 20 --json &
wait

# Each agent works independently
gibil run task-1 "cd /root/project && pnpm test" --json
gibil run task-2 "cd /root/project && pnpm build" --json
gibil run task-3 "cd /root/project && pnpm lint" --json

# Destroy all when done
gibil destroy --all --json

Or use fleet mode for identical VMs:

gibil create --name fleet --fleet 5 --repo https://github.com/you/project --ttl 15 --json

Error handling

Your agent should handle failures gracefully:

# Run tests, check exit code
RESULT=$(gibil run agent-task "cd /root/project && pnpm test" --json)
EXIT_CODE=$(echo "$RESULT" | jq .exit_code)

if [ "$EXIT_CODE" -ne 0 ]; then
  # Tests failed — get the output
  echo "$RESULT" | jq -r .stderr

  # Still destroy the VM
  gibil destroy agent-task --json
  exit 1
fi

gibil destroy agent-task --json

Always destroy VMs in your error path. If your agent crashes, the TTL will auto-destroy the server — but explicit cleanup is faster and cheaper.

JSON output schemas

Every command returns predictable JSON. See the JSON Output Reference for complete schemas.

// gibil create --json
{ "name": "agent-task", "ip": "49.13.42.101", "status": "ready" }

// gibil run --json
{ "stdout": "...", "stderr": "...", "exit_code": 0 }

// gibil destroy --json
{ "name": "agent-task", "status": "destroyed" }

Next steps

Use with Claude Code — MCP integration for Claude
Remote PR Workflow — commit, push, and open PRs from VMs
JSON Output Reference — complete output schemas