Core Concepts

Before diving deeper into SCC, it’s helpful to understand the key concepts that make it work.

Providers

A provider is an AI coding agent that SCC can run inside a governed sandbox. SCC currently supports two providers:

• Claude Code — Anthropic’s AI coding CLI
• Codex — OpenAI’s AI coding CLI

SCC is provider-neutral: the same org config, team plugins, safety policies, and governance apply regardless of which agent you use. Each provider has its own container image, auth flow, settings format, and credential storage — SCC handles the differences through provider-specific adapters.

scc provider show          # See current preference
scc provider set codex     # Default to Codex
scc start --provider claude  # Override for one session

Provider preference resolution:

1. --provider CLI flag (highest priority)
2. Resume provider (when resuming a session)
3. If global preference is ask, SCC still prompts when multiple providers are viable
4. Workspace last-used helps SCC preselect or reuse the provider that worked last in this repo
5. Global preference (claude or codex) applies when ask is not set
6. If only one provider is viable, SCC uses it automatically

SCC remembers the last-used provider per workspace, so repeated launches feel natural. If you set scc provider set ask, SCC still prompts when both providers are allowed, but it uses workspace context to start from a sensible default instead of forcing you to choose from scratch every time.

Tip

Organizations can allow Claude, Codex, or both. That makes it practical for one team to standardize on a single provider while another keeps both available and chooses per task.

Note

Claude Code and Codex have different native plugin, rules, and hook surfaces. SCC unifies governance at the approval/bundle level — it does not pretend they share an identical plugin format. Each provider’s native configuration is rendered by a provider-specific adapter.

Sessions

A session is a running agent environment inside a container. Each session:

• Is tied to a specific workspace (git repository)
• Uses a specific provider (Claude Code or Codex)
• Uses a specific team profile
• Can be named for easy identification
• Can be resumed after stopping

# Start a new session
scc start ~/project

# Resume the most recent session
scc start --resume

# Pick from recent sessions interactively
scc start --select

Session Lifecycle

Session Lifecycle Flow

The full operator lifecycle:

scc                    # Smart start (auto-detect, Quick Resume)
scc sessions           # List recent sessions
scc list               # List running containers
scc status             # Show current state
scc stop               # Stop a sandbox (interactive picker)
scc stop --all         # Stop all sandboxes
scc prune              # Remove stopped containers

Sandbox Conflicts

When you start a session and a container already exists for your workspace and provider:

• Stale sandbox (stopped) — automatically replaced
• Live sandbox (running) — SCC prompts: keep the existing session, replace it, or cancel
• Force new — use scc start --fresh to always create a new container

Sandboxes

A sandbox is the OCI container that isolates the agent from your host system. The sandbox:

• Has access only to mounted directories (your project workspace)
• Cannot access sensitive host files like ~/.ssh or ~/.aws
• Uses your org’s network policy for egress control
• Runs a specific provider container image (e.g., scc-agent-claude or scc-agent-codex)
• Has a persistent volume for credential and data storage per provider

Note

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

Caution

Container isolation protects the host filesystem, but it does not automatically restrict outbound network access. Use web-egress-enforced or locked-down-web when you need stronger network controls.

Team Profiles

A team profile defines the configuration for a group of users. Each profile includes:

Setting	Description
plugins	Agent plugins enabled for this team
mcp_servers	MCP servers available to the agent
network_policy	Network egress policy (open, web-egress-enforced, or locked-down-web)
session	Timeout settings (auto_resume is advisory in v1)

Profiles are defined in your organization’s config and can be:

• Inline: Defined directly in the org config file
• Federated: Defined in a separate team-managed repository

# List available teams/profiles
scc team list

# Switch to a different team
scc team switch

# See current team
scc team current

# See team configuration
scc team info <team-name>

Personal Profiles

A personal profile captures your own agent preferences for a specific project. It sits between team config and workspace overrides so you can add your own plugins or MCP servers without changing org or repo settings, while still respecting org security blocks.

# Save current workspace settings as a personal profile
scc profile save

# Apply personal profile on demand
scc profile apply

Note

When SCC applies a profile, it enforces org security blocks and stdio MCP gating. Manual edits to local workspace files are advisory.

Learn more in Personal Profiles.

Worktrees

A worktree is a git feature that lets you check out multiple branches simultaneously in different directories. SCC uses worktrees to:

• Isolate AI experiments from your main branch
• Allow parallel development on multiple features
• Keep your main branch clean

# Create a worktree and auto-start an agent session
scc worktree create ~/project feature-auth

# Create without starting a session
scc worktree create ~/project feature-auth --no-start

# List all worktrees
scc worktree

# Enter a worktree (starts a subshell)
scc worktree enter feature-auth

# Switch between worktrees
scc worktree switch feature-auth

Tip

Protected branch behavior: When starting a session on main or master, SCC shows a visual speed bump warning and offers to create a feature branch. If you continue on the protected branch, git push hooks block direct pushes.

Tip

Branch names with / are sanitized to - in worktree directory names. For example, feature/auth becomes feature-auth.

Configuration Layers

SCC uses layered configuration with personal profiles:

Configuration Layers

Order of precedence:

Organization → Team → Personal Profile → Workspace overrides

Safety Engine

SCC includes a built-in safety engine that runs inside every container:

• Git safety rules — blocks destructive commands like push --force, reset --hard, branch -D
• Network tool interception — wraps curl, wget, ssh, scp, sftp, rsync with policy checks
• Shell tokenizer — parses compound commands to catch destructive operations in pipes or subshells
• Fail-closed — if safety policy cannot be loaded, all guarded commands are blocked by default

The optional scc-safety-net plugin provides additional coverage via agent-native hooks (currently Claude Code; Codex support planned).

Network Policy

SCC controls what network access the agent has inside the container:

Policy	Effect
open	No restriction — unrestricted egress (default)
web-egress-enforced	Topology-enforced proxy: agent runs on an internal-only network and can only reach the internet through a Squid proxy sidecar with an ACL. Even if the agent ignores proxy env vars, it physically cannot bypass the proxy.
locked-down-web	--network=none — no external network access at all

Network policy is configured at the org or team level in the org config JSON. See Security Model for details on how topology enforcement works.

Plugins

Plugins extend the agent with additional capabilities. SCC manages plugins through:

• Marketplaces: Repositories of approved plugins
• Allowlists: Patterns defining which plugins are permitted
• Blocklists: Patterns defining which plugins are forbidden

The most important official plugin is scc-safety-net, which provides agent-native hook-based protection in addition to SCC’s built-in safety engine. Today that plugin is Claude-focused; Codex support is planned, while the built-in engine already protects both providers.

Note

Claude Code and Codex have different native plugin surfaces. SCC unifies plugin governance at the approval/bundle level and renders provider-native configuration through adapters. Plugins are not a one-to-one mapping between providers.

MCP Servers

MCP (Model Context Protocol) servers provide the agent with access to external tools and data. Types include:

Type	Description	Example
HTTP	Remote API endpoints	context7, shadcn
SSE	Server-Sent Events streaming	Real-time data feeds
Stdio	Local subprocess servers	Playwright, custom tools

Caution

Stdio MCP servers require explicit organization approval via allow_stdio_mcp: true because they run local processes.

Glossary

Term	Definition
Provider	An AI coding agent that SCC can run (Claude Code, Codex)
Session	A running agent environment in a container
Sandbox	The OCI container providing isolation
Profile	Team configuration (plugins, servers, policies)
Worktree	Isolated git checkout for parallel development
Workspace	The directory mounted into the sandbox
Marketplace	Repository of approved plugins
Safety Engine	SCC’s built-in fail-closed command interception system
Safety Net	Optional plugin for additional agent-native hook protection

Next Steps

Developer Guide

Learn the day-to-day workflow. Read guide →

Configuration Reference

Dive into config file details. See reference →