Container Runtime Issues

Container Runtime Not Running

Symptoms: “Cannot connect to Docker daemon” or container runtime not detected by scc doctor

Fix:

# macOS — start your runtime
open -a OrbStack          # If using OrbStack
colima start              # If using Colima
open -a Docker            # If using Docker Desktop

# Linux
sudo systemctl start docker

# Verify
docker info

SCC works with Docker Engine, OrbStack, Colima, or Docker Desktop. It auto-detects the available runtime — Docker Desktop is not required.

Provider Image Missing

Symptoms: scc doctor shows “Image not found” for a provider, or scc start fails with an image error

SCC auto-builds provider images on first use. If the build failed or the image was removed:

# Check which images exist
docker images | grep scc-agent

# Manually build the missing image
docker build -t scc-agent-claude:latest images/scc-agent-claude/
docker build -t scc-agent-codex:latest images/scc-agent-codex/

scc doctor --provider claude (or --provider codex) shows the exact build command if the image is missing.

Container Won’t Start

Symptoms: Stuck at “Starting container…”

Fix:

scc stop --all
docker system prune -f
scc start --fresh

Sandbox Conflict

Symptoms: “A sandbox already exists for this workspace”

Situation	What happens
Stale (stopped)	Automatically replaced
Live (running)	SCC prompts: keep / replace / cancel
Force new	Use `scc start --fresh`

Permission Denied

Symptoms: Docker permission errors on Linux

Fix:

sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Container Cleanup

Remove old containers:

scc prune              # Remove stopped SCC containers
scc stop --all         # Stop all running SCC containers
docker container prune # Remove all stopped Docker containers

Provider Auth Issues

Symptoms: “Auth missing” or “Sign-in needed” in scc doctor output

Fix:

# Re-run setup to reconnect providers
scc setup

# Or just start a session — SCC triggers browser sign-in automatically
scc start

Codex Auth Callback Failed

Codex uses localhost:1455 for its OAuth callback. If auth fails:

Ensure port 1455 is free: lsof -i :1455
Kill any process using the port and retry
Try closing and reopening the browser

Auth Readiness States

State	Meaning	Action
Launch-ready	Auth + image present	Ready to go
Auth cache present	Auth OK, image missing	SCC auto-builds on start
Image available	Image OK, auth missing	SCC triggers sign-in on start
Sign-in needed	Nothing present	Run `scc setup` or start a session and let SCC bootstrap auth

Network Policy Issues

web-egress-enforced not working

The web-egress-enforced policy creates an internal Docker network with a Squid proxy sidecar. If requests fail:

# Check if proxy container is running
docker ps | grep scc-proxy

# Check the egress proxy image
docker images | grep scc-egress-proxy

If the proxy image is missing, rebuild it:

docker build -t scc-egress-proxy images/scc-egress-proxy/