9.1. 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 Settings > Container.

2. The Runtime field shows the detected backend:

   • Apple Container — Apple Container detected and preferred
   • Docker — Docker is available
   • Not available — No runtime found (re-check installation)

You can also query the Management API directly:

curl http://localhost:55765/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 Settings > Container.

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 CLI¶

aigo container build-image

Build via Management API¶

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

Check Image Status¶

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

Response:

{
  "exists": true,
  "imageTag": "aigo-agent-runner:latest",
  "message": "Image is ready"
}

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. Go to Settings > Container > Mount Security.

2. 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:55765/api/v1/container/mount/allowlist

# Set allowlist
curl -X PUT http://localhost:55765/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:55765/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.

Start the Proxy¶

1. Go to Settings > Container > Credential Proxy.

2. Toggle Enable Credential Proxy to on.

3. The proxy starts automatically on port 3001 (configurable).

Add a Credential Mapping¶

1. Click Add Mapping in the Credential Proxy settings.

2. Fill in:

   • Name: A human-readable label (e.g., "Anthropic API")
   • Upstream URL: The real API endpoint (e.g., https://api.anthropic.com)
   • Credential Type: API Key or OAuth Bearer
   • Real Credential: Your actual API key (stored encrypted on-host)

3. Click Save.

The proxy generates a unique placeholder for each mapping. Containers use the placeholder in their API calls — the proxy substitutes the real key automatically.

Next Steps¶

• Squad Container Mode — Enable container execution for squad agents
• Task Scheduling — Schedule container tasks to run automatically
• Security Model — Deep dive into security layers