9.2. Squad Container Mode¶

Squad Container Mode runs individual squad agents inside isolated containers, providing stronger security boundaries and reproducible execution environments. You can enable container mode per-agent within a squad, so some agents run in-process while others run in containers.

Prerequisites¶

Before enabling container mode, complete the Container Execution Guide:

• Container runtime installed (Docker or Apple Container)
• Agent runner image built (aigo-agent-runner:latest)
• Mount allowlist configured
• Credential proxy running (if agents need external API access)

How It Works¶

When an agent runs in container mode:

sequenceDiagram
    participant Host as Backend.AI GO Host
    participant NS as Namespace Manager
    participant C as Container
    participant CP as Credential Proxy

    Host->>NS: Create session directory
    NS->>C: Start container with workspace mounts
    C->>CP: API request (with placeholder credential)
    CP->>CP: Substitute real credential
    CP-->>C: Forwarded request with real credential
    C->>Host: IPC: send message / create task
    Host-->>C: IPC: follow-up message
    C->>Host: IPC: close (task complete)
    Host->>C: Container stops

Each container receives:

• /workspace — the squad's shared workspace directory (read-write for main agents, read-only for others)
• /workspace/extra/{name} — additional mounts you configure
• /workspace/ipc — the IPC directory for host-container communication
• .claude/ — the agent's SDK session state

Step 1: Create or Edit a Squad¶

1. Go to Squad in the sidebar.

2. Click New Squad or open an existing squad.

3. Configure the squad's workspace directory if not already set.

Step 2: Enable Container Mode for an Agent¶

1. In the squad editor, click on the agent you want to containerize.

2. In the agent configuration panel, find Execution Mode.

3. Select Container from the dropdown (default is In-Process).

4. The container configuration options appear:

   Field	Default	Description
   Image	aigo-agent-runner:latest	Container image to use
   Timeout	30 minutes	Maximum execution time
   Idle Timeout	None	Kill container if no output for this duration
   Additional Mounts	Empty	Extra host paths to mount

Step 3: Configure Additional Mounts (Optional)¶

If the agent needs access to host paths beyond the workspace:

1. Click Add Mount in the agent's container configuration.

2. Fill in:

   • Host Path: The path on the host to mount (must be in the mount allowlist)
   • Container Path: Where to mount it inside the container (must be under /workspace/extra/)
   • Read-Only: Toggle on to prevent the agent from writing to this path

3. Click Add.

Step 4: Configure Group Namespaces¶

Group namespaces organize containers into isolated session groups. Each group gets its own session directory and instruction set.

Create a Group Namespace¶

1. Go to Settings > Container > Groups.

2. Click New Group.

3. Enter a Name (filesystem-safe, e.g., dev-team).

4. Optionally add a Description.

5. Click Create.

Set Group Instructions¶

Group-specific instructions (equivalent to CLAUDE.md) are injected into every container session for that group:

1. Click the group name in the Groups list.

2. Click Edit Instructions.

3. Enter your instructions (Markdown supported).

4. Click Save.

Global Instructions¶

Global instructions apply to all groups. They are combined with group-specific instructions and merged for each container:

1. Go to Settings > Container > Groups.

2. Click Edit Global Instructions.

3. Enter your global directives.

4. Click Save.

Step 5: Run the Squad¶

1. Click Run in the squad panel.

2. Submit your task description.

3. The planner creates a task graph and assigns tasks to agents.

4. When a task is assigned to a container-mode agent:

   • A session directory is created under DATA_DIR/sessions/{group}/
   • The container is started with the workspace and IPC mounts
   • The agent processes the task and communicates results via IPC
   • The container stops when the task completes or times out

Monitoring Container Execution¶

Container Status Panel¶

The squad monitoring dashboard shows container-specific status:

Run History¶

1. Go to Settings > Container > Run History.

2. View past container executions with start time, duration, exit code, and output.

Audit Log¶

1. Go to Settings > Container > Audit Log.

2. Browse security events, permission checks, and mount validations.

Troubleshooting Container Mode¶

Agent container does not start¶

• Verify the agent runner image exists: Settings > Container > Image Status
• Check the runtime is available: curl http://localhost:55765/api/v1/container/runtime
• Review the audit log for permission errors

Agent cannot write to workspace¶

• Confirm the squad workspace directory is under an allowed root
• Check that the agent is designated as a main agent (only main agents get read-write workspace access)

Container times out¶

• Increase the timeout in the agent's container configuration
• Review the container logs in the run history for slow steps
• Consider splitting the task into smaller subtasks

API calls fail inside container¶

• Verify the credential proxy is running: Settings > Container > Credential Proxy
• Confirm the correct credential mapping exists for the upstream API
• Check that the container's environment has the correct ANTHROPIC_BASE_URL pointing to the proxy

API Reference¶