Container Execution Guide¶

This guide walks you through setting up the container runtime, building the agent runner image, and configuring mount security before running agents in containers.

Step 1: Install a Container Runtime¶

Backend.AI GO supports two container runtimes:

• Apple Container — preferred on Apple Silicon Macs, lighter-weight than Docker
• Docker — supported on all platforms (macOS, Windows, Linux)

Apple Container (macOS Apple Silicon only)¶

1. Download the Apple Container installer from the Apple Container GitHub releases page.

2. Open the downloaded .pkg file and follow the installation wizard.

3. After installation, verify it works:

   container --version
   

4. Start the container system service:

   container system start
   

Docker¶

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker version

Step 2: Verify Runtime Detection¶

Backend.AI GO automatically detects the best available container runtime on startup.

1. Open Squad > Teams.

2. Check the container-runtime badge in the page header. It shows whether a supported runtime is available. Use the Management API below when you need the detected backend and version.

You can also query the Management API directly:

curl http://localhost:8001/api/v1/container/runtime

Example response:

{
  "available": true,
  "backend": "apple_container",
  "version": "0.2.0",
  "networking": {
    "hostGateway": "192.168.64.1",
    "extraRunArgs": []
  },
  "message": "Apple Container runtime detected"
}

Step 3: Build the Agent Runner Image¶

The agent runner image (aigo-agent-runner:latest) is a pre-configured container image that includes the Claude Code SDK and supporting tools needed by squad agents.

Build from the App¶

1. Go to Squad > Settings.

2. Click Build Agent Image.

3. The build process runs in the background. Progress is shown in the build log panel.

4. When the status shows Image ready, the build is complete.

Build via Management API¶

curl -X POST http://localhost:8001/api/v1/container/image/build \
  -H "Content-Type: application/json" \
  -d '{"tag": "aigo-agent-runner:latest"}'

Check Image Status¶

curl http://localhost:8001/api/v1/container/image/status

Response:

{
  "exists": true,
  "tag": "aigo-agent-runner:latest"
}

Step 4: Configure the Mount Allowlist¶

The mount allowlist controls which host directories containers are permitted to access. Only paths under an allowed root can be mounted — all other paths are rejected.

Default Blocked Patterns¶

The following path component patterns are always blocked, regardless of allowlist settings:

Adding Allowed Roots¶

1. Open Chat, select Cowork mode, and open the Cowork settings drawer.

2. Select Mount Security, then click Add Allowed Root.

3. Select a host directory (e.g., /Users/you/projects).

4. Click Save.

Only subdirectories of the added roots can be mounted into containers.

Via Management API¶

# Get current allowlist
curl http://localhost:8001/api/v1/container/mount/allowlist

# Set allowlist
curl -X PUT http://localhost:8001/api/v1/container/mount/allowlist \
  -H "Content-Type: application/json" \
  -d '{
    "allowedRoots": ["/Users/you/projects", "/Users/you/data"],
    "blockedPatterns": [".ssh", ".gnupg", ".env", ".aws", ".azure", ".gcloud", ".docker", ".kube"]
  }'

Validate a Mount Path¶

Before running containers, you can validate whether a specific path would be allowed:

curl -X POST http://localhost:8001/api/v1/container/mount/validate \
  -H "Content-Type: application/json" \
  -d '{"hostPath": "/Users/you/projects/myapp", "containerPath": "/workspace/extra/myapp", "readOnly": true}'

Step 5: Configure the Credential Proxy¶

The credential proxy ensures API keys never enter containers. Containers receive a placeholder token and communicate with the proxy at http://host-gateway:3001, which substitutes real credentials before forwarding requests to the upstream API.

The current navigation does not expose a Credential Proxy settings tab. Configure it through the Management API:

# Start the proxy on its configured port (default: 3001)
curl -X POST http://localhost:8001/api/v1/container/credential-proxy/start

# Read the credential into a shell variable without echoing it.
printf "Credential: "
IFS= read -rs CREDENTIAL
printf '\n'

# Add an in-memory mapping without placing the credential in process arguments.
printf '%s' "$CREDENTIAL" \
  | python3 -c 'import json,sys; print(json.dumps({"id":"anthropic","upstreamUrl":"https://api.anthropic.com","authMode":"api_key","credential":sys.stdin.read()}))' \
  | curl -X POST http://localhost:8001/api/v1/container/credential-proxy/mappings \
  -H "Content-Type: application/json" \
  --data-binary @-

unset CREDENTIAL

Use oauth_bearer instead of api_key when the upstream expects an OAuth bearer token. Mappings live in the running process and are not returned in status responses.

Containers see only the placeholder string CREDENTIAL_PROXY_PLACEHOLDER; the proxy injects the real credential when forwarding the request.

Next Steps¶

• Squad Container Mode — Enable container execution for squad agents
• Task Scheduling — Schedule container tasks to run automatically
• Security Model: How each security layer works