Skip to content

9.3. Cowork Container Mode

Cowork Container Mode runs a single Cowork (ReAct agent) session inside an isolated container. This provides the same security benefits as Squad Container Mode for multi-agent workflows — but for individual agent tasks.

When to Use Container Mode

Use Cowork Container Mode when:

  • The task involves writing or executing code and you want strong filesystem isolation
  • You need a reproducible environment regardless of your host system's state
  • The task requires specific tools or dependencies available in the container image
  • You want to prevent accidental modification of host files beyond the workspace

Prerequisites

Complete the Container Execution Guide before enabling container mode:

  • Container runtime installed and detected
  • Agent runner image built
  • Mount allowlist configured

Enabling Container Mode

Via Cowork Settings

  1. Open the Cowork panel from the sidebar.

  2. Click the settings icon (gear) next to the agent profile selector.

  3. In Advanced Settings, find Execution Mode.

  4. Select Container (default is In-Process).

  5. Configure the container options:

    Option Default Description
    Image aigo-agent-runner:latest Container image
    Timeout 30 minutes Maximum execution time
    Idle Timeout None Kill if no output for this duration

  6. Click Save.

Workspace in Container Mode

When Cowork runs in container mode, the agent's workspace is mounted into the container:

Container filesystem:
/workspace/               ← Agent's read-write workspace (from host)
/workspace/extra/{name}/  ← Additional mounts (read-only by default)
/workspace/ipc/           ← IPC communication directory

The workspace directory corresponds to the folder permissions you have configured in Cowork. The main permitted folder is mounted as /workspace.

Folder Permissions Still Apply

Container mode does not bypass folder permissions. Only folders you have explicitly permitted in Cowork settings are mounted into the container.

Additional Mounts

If the agent needs access to additional host paths:

  1. Go to Cowork > Settings > Container > Additional Mounts.

  2. Click Add Mount.

  3. Fill in:

    • Host Path: Path on your host machine (must be in the allowlist)
    • Container Path: Must be under /workspace/extra/
    • Read-Only: Recommended for reference data

IPC Communication

Cowork container agents communicate with the host via the same file-based IPC system used by Squad container agents:

  • Follow-up messages: Host writes to ipc/input/ to send steering messages
  • Outgoing messages: Container writes to ipc/messages/ to request message sends
  • Task creation: Container writes to ipc/tasks/ to create new tasks
  • Close signal: Host writes ipc/input/_close to request graceful shutdown

Credential Proxy

When the agent makes API calls (e.g., to Anthropic Claude), the calls go through the credential proxy:

  • Inside the container, ANTHROPIC_API_KEY is set to CREDENTIAL_PROXY_PLACEHOLDER
  • ANTHROPIC_BASE_URL points to http://host-gateway:3001 (the credential proxy)
  • The proxy substitutes the real API key before forwarding to api.anthropic.com

Ensure the credential proxy is running and has the correct mapping for your API provider. See Container Execution Guide.

Monitoring Container Execution

Status Indicators

When running in container mode, the Cowork status badge shows container-specific states:

Status Description
provisioning Container is being started
running Container is processing your task
completed Container finished successfully
failed Container exited with an error
timeout Execution exceeded the time limit

Run History

View past container executions:

curl http://localhost:55765/api/v1/container/run-history

Metrics

curl http://localhost:55765/api/v1/container/metrics

Differences from Squad Container Mode

Feature Cowork Container Squad Container
Number of agents Single Multiple
Group namespace Per-session Per-group namespace
Workspace From folder permissions Squad workspace directory
IPC Yes Yes
Credential proxy Yes Yes
Scheduling No Yes (via Task Scheduling)
Channel routing No Yes (via Channel-Squad Mapping)

Troubleshooting

Container does not start in Cowork

  • Check that the container runtime is detected: Settings > Container > Runtime
  • Verify the agent runner image is built: Settings > Container > Image Status
  • Ensure the workspace directory is in the mount allowlist

Agent cannot access workspace files

  • Verify the folder is in Cowork's permitted folders list
  • Check the mount allowlist includes the folder's parent directory
  • Review the audit log: Settings > Container > Audit Log

Steering messages not reaching the agent

  • Container mode supports mid-task steering via the IPC input/ directory
  • Check that the IPC directory was created: look for ipc/input/ in the session directory
  • Verify the container is still running (check run history)

Task times out

  • Increase the container timeout in Cowork settings
  • Consider breaking the task into smaller steps
  • Check the container logs for slow or stuck operations