Run Claude Code in Docker

Running Claude Code in Docker provides isolation, reproducibility, and team consistency. SCC CLI makes this straightforward.

Why Docker for Claude Code

Benefit	What It Means
Isolation	AI 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

Prerequisites

macOS

# Docker Desktop 4.50+
brew install --cask docker

# Start Docker Desktop and ensure engine is running

# Python 3.10+
brew install python@3.12

# Git 2.30+
brew install git

Windows

# Docker Desktop 4.50+
winget install Docker.DockerDesktop

# Start Docker Desktop and ensure engine is running

# Python 3.10+
winget install Python.Python.3.12

# Git 2.30+
winget install Git.Git

Linux

# Docker Engine or Docker Desktop
# Follow Docker's official installation guide for your distro

# Python 3.10+
sudo apt install python3.12  # Debian/Ubuntu

# Git 2.30+
sudo apt install git

Quick Start

# Install SCC CLI
uv tool install scc-cli

# Configure SCC (one-time setup)
scc setup

# Start Claude Code in Docker
scc start ~/your-project

That’s it. Claude Code now runs inside a Docker container with your project mounted.

How It Works

When you run scc start, SCC:

1. Creates a container based on configured image
2. Mounts your workspace at a controlled path
3. Applies team configuration (plugins, policies)
4. Starts Claude Code inside the container
5. Manages the session (resume, stop, cleanup)

┌─────────────────────────────────────┐
│            Your Machine             │
│                                     │
│  ~/your-project                     │
│       │                             │
│       ▼ (mounted read-write)        │
│  ┌─────────────────────────────┐    │
│  │     Docker Container        │    │
│  │  /workspace/your-project    │    │
│  │                             │    │
│  │  Claude Code runs here      │    │
│  │  + Team plugins             │    │
│  │  + Safety Net               │    │
│  │  + Network policies         │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Configuration Options

Workspace Mounting

By default, SCC mounts the directory you specify:

scc start ~/projects/my-app  # Mounts ~/projects/my-app

Team Profiles

If your organization has profiles configured:

scc start --team backend ~/project  # Use backend team profile
scc start --team frontend ~/project  # Use frontend team profile

Session Management

# List active sessions
scc session list

# Resume a previous session
scc start --resume ~/project

# Stop a session
scc session stop <session-id>

Docker Requirements

SCC requires:

• Docker Desktop 4.50+ (macOS, Windows) or Docker Engine (Linux)
• Docker Engine running when you use SCC
• Sufficient disk space for container images

Tip

SCC caches container images after first use. Subsequent starts are faster.

Verifying Docker Setup

# Check Docker is running
docker info

# Check Docker version
docker --version

# Verify SCC can access Docker
scc doctor

Troubleshooting

Docker Not Running

Error: Cannot connect to Docker daemon

Start Docker Desktop or Docker Engine, then retry.

Permission Issues

Error: Permission denied while trying to connect to Docker daemon

On Linux, add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

Image Pull Failures

Error: Failed to pull image

Check network connectivity and Docker Hub access. For air-gapped environments, pre-pull images or configure a local registry.

Advanced Usage

Dry Run

Preview what would happen without actually starting:

scc start --dry-run ~/project

JSON Output

Get machine-readable output for scripting:

scc start --dry-run --json ~/project

Custom Network Policy

Network policies are configured at the org/team level:

{
  "defaults": {
    "network_policy": "isolated"
  }
}

Next Steps

Quick Start Complete installation guide

Security Model Understand isolation layers

Troubleshooting Docker Solve Docker-related issues