Quick Start

Note

Prerequisites: Python 3.10+, a container runtime (Docker Engine 20.10+, OrbStack, Colima, or Docker Desktop), Git 2.30+. See Installation for details.

Tip

If you only read three pages, make it these: this page, Core Concepts, and Daily Workflow. That is enough for most developers to install SCC, understand the model, and use it day to day.

30-Second Setup

1. Install SCC CLI

   uv (recommended)

   uv tool install scc-cli

   pipx

   pipx install scc-cli

   pip

   pip install scc-cli

2. Configure your organization and connect providers

   scc setup

   When prompted:

   • Paste your organization’s config URL (or use --standalone if you don’t have one)
   • Connect providers — authenticate Claude Code, Codex, or both via browser sign-in
   • Set provider preference — choose ask (prompt every time), claude, or codex
   • If your org allows both providers, choose the one that best fits the task or keep both available

   Tip

   Private org config? Use a token with --auth env:SCC_ORG_TOKEN (or GITHUB_TOKEN / GITLAB_TOKEN). GitLab URLs use the PRIVATE-TOKEN header automatically. See Config Setup for hosting and auth examples.

3. Launch an agent session in your project

   cd ~/your-project
   scc

   Or specify the path and provider directly:

   scc start --provider codex ~/your-project

Tip

The first time you start a session with a provider, SCC automatically builds the container image from bundled Dockerfiles. This takes a few minutes once — subsequent launches use the cached image.

What Happens When You Run scc

1. If no org config exists, SCC asks whether to run setup or standalone mode
2. Auto-detects workspace from git repository root or .scc.yaml location
3. Resolves provider — uses --provider first, keeps the original provider when resuming, then applies your saved preference and workspace context before prompting if multiple providers are still viable
4. Checks readiness — verifies provider image availability and provider auth cache; auto-builds the image or triggers browser sign-in if needed
5. If on a protected branch (main/master), shows a speed bump and offers to create a feature branch
6. Shows Quick Resume (always includes “New session” as the default)
7. Prints brief context (workspace root, entry directory, team, provider) before launching
8. Starts a sandboxed container with your team’s configuration

Tip

Safety guard: SCC won’t auto-launch from suspicious directories (home, /tmp). If you try scc start ~/, it will prompt for confirmation. In non-interactive mode, pass --allow-suspicious-workspace only if you explicitly intend to run there.

Managing Providers

scc provider show          # Show current preference (ask, claude, or codex)
scc provider set codex     # Default to Codex
scc provider set ask       # Prompt every time
scc start --provider claude  # Override for one session

SCC remembers the last-used provider per workspace — repeated launches default to what you used last time, unless you set a global preference or use --provider.

If you set scc provider set ask, SCC still prompts when both providers are viable. It uses workspace context to preselect a sensible default so switching stays quick without silently forcing a provider.

Session Lifecycle

SCC manages the full lifecycle of agent sessions:

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

Sandbox conflicts: If a container already exists for your workspace and provider:

• Stale (stopped) — automatically replaced
• Live (running) — SCC prompts: keep, replace, or cancel
• Use scc start --fresh to always create a new container

Keyboard Shortcuts

When in the dashboard:

Key	Action
↑↓	Navigate list
Enter	Open action menu (containers/sessions/worktrees)
Tab	Switch to next tab
Shift+Tab	Switch to previous tab
n	Start new session
t	Switch team
r	Refresh
s	Settings & Maintenance
p	Profile quick menu
?	Help
q	Quit

Verify Your Setup

Run the diagnostic command to ensure everything is configured correctly:

scc doctor
scc doctor --provider codex   # Check a specific provider

Expected output:

✓ Container runtime: OK (docker 27.0.0)
✓ Git: OK (version 2.45.0)
✓ Python: OK (version 3.12.0)
✓ Config: OK
✓ Organization: Connected to "My Org"
✓ Team: backend
✓ Claude Code: Launch-ready
✓ Codex: Auth cache present (image needs building)

Provider readiness states:

State	Meaning
Launch-ready	Auth and image both present — ready to start
Auth cache present	Auth exists but image needs building (auto-built on first start)
Image available	Image exists but auth is missing
Sign-in needed	Neither auth nor image — run scc setup

Caution

A container alone does not limit outbound network access. If your team is worried about agents reaching internal or external services, use web-egress-enforced or locked-down-web — not just a default container runtime.

Common First-Time Issues

Problem	Solution
”Cannot connect to container runtime”	Start Docker Engine, OrbStack, Colima, or Docker Desktop and wait for it to initialize
”Provider image missing”	SCC auto-builds on first start. Manual: docker build -t scc-agent-<provider>:latest images/scc-agent-<provider>/
”Organization config fetch failed”	Check your org URL is correct and accessible
”Codex auth callback failed”	Ensure port 1455 is free — Codex uses localhost:1455 for OAuth

See Troubleshooting for more solutions.

Next Steps

Core Concepts

Understand providers, sessions, worktrees, and profiles. Learn more →

Personal Profiles

Save your personal setup per project and sync across machines. Read guide →

Developer Onboarding

Joining a team? See what you get automatically. Read guide →

Team Setup

Managing a team? Configure plugins and profiles. Set up →