Run AI Coding Agents in Containers

Running AI coding agents in containers provides isolation, reproducibility, and team consistency. SCC makes this straightforward for both Claude Code and Codex.

Some teams standardize on one provider. Others allow both and choose the agent that fits the task. SCC keeps the runtime, safety, and governance model consistent either way.

Tip

If you are new to SCC, do not start with every architecture page. Read Quick Start, then Core Concepts, then come back here if you want the container and runtime details.

Why Containers for AI Coding

Benefit	What It Means
Isolation	Agent execution separated from host system
Reproducibility	Same environment across all team members
Clean state	Each session starts fresh (or can resume)
Controlled access	Only mounted directories are visible
Provider choice	Run Claude Code or Codex through the same governed pipeline

Prerequisites

• Python 3.10+
• Container runtime — Docker Engine 20.10+, OrbStack, Colima, or Docker Desktop
• Git 2.30+

SCC auto-detects the available runtime. Docker Desktop is not required.

Quick Start

# Install SCC CLI
uv tool install scc-cli

# Configure and connect providers (one-time)
scc setup

# Start an agent in a container
scc start ~/your-project

# Or specify a provider explicitly
scc start --provider codex ~/your-project

How It Works

When you run scc start, SCC:

1. Resolves provider — CLI flag first, resumed session provider when applicable, then saved preference and workspace context before prompting if multiple providers are still viable
2. Checks readiness — verifies container image and auth (auto-builds image on first run)
3. Creates a container from the provider-specific image (e.g., scc-agent-claude or scc-agent-codex)
4. Mounts your workspace at a controlled path
5. Applies team configuration — plugins, MCP servers, network policy, safety policy
6. Starts the agent inside the container
7. Manages the session — resume, stop, cleanup

┌─────────────────────────────────────┐
│            Your Machine             │
│                                     │
│  ~/your-project                     │
│       │                             │
│       ▼ (mounted read-write)        │
│  ┌─────────────────────────────┐    │
│  │    Container Sandbox        │    │
│  │  /workspace/your-project    │    │
│  │                             │    │
│  │  Agent (Claude/Codex)       │    │
│  │  + Team plugins             │    │
│  │  + Built-in safety engine   │    │
│  │  + Network policy           │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Container Images

SCC owns provider-specific images built from bundled Dockerfiles:

Image	Purpose
scc-base	Shared base with safety wrappers and evaluator
scc-agent-claude	Claude Code agent (extends scc-base)
scc-agent-codex	Codex agent (extends scc-base)
scc-egress-proxy	Squid proxy sidecar for web-egress-enforced

First-run build: SCC auto-builds the image on first start (~2–3 min). Manual build:

docker build -t scc-agent-claude:latest images/scc-agent-claude/
docker build -t scc-agent-codex:latest images/scc-agent-codex/

Session Management

scc sessions             # List recent sessions
scc list                 # List running containers
scc start --resume       # Resume most recent session
scc start --select       # Pick from recent sessions
scc stop                 # Stop a sandbox (interactive picker)
scc stop --all           # Stop all sandboxes
scc prune                # Remove stopped containers

Network Policy

Network policies are configured at the org/team level:

{
  "defaults": {
    "network_policy": "web-egress-enforced"
  }
}

Policy	Effect
open	No restriction — unrestricted egress
web-egress-enforced	Topology-enforced proxy sidecar (HTTP/HTTPS, IPv4)
locked-down-web	--network=none — no external access

web-egress-enforced is the important middle ground for many teams: the agent still gets controlled web access, but it cannot bypass the proxy because the container itself is on an internal-only network.

Verifying Setup

scc doctor                      # Full health check
scc doctor --provider codex     # Check specific provider

Troubleshooting

Problem	Solution
”Cannot connect to container runtime”	Start Docker Engine, OrbStack, Colima, or Docker Desktop
”Provider image missing”	SCC auto-builds on first start. Manual: docker build -t scc-agent-<provider>:latest images/scc-agent-<provider>/
Permission denied on Linux	sudo usermod -aG docker $USER then log out/in

Next Steps

Quick Start Complete setup guide

Security Model Isolation layers, safety engine, network enforcement

Troubleshooting Solve container runtime issues