scc-cli 1.5.2

Run Claude Code in Docker sandboxes with team configs and git worktree support

SCC - Sandboxed Claude CLI

Quick Start · Commands · CLI Reference · Configuration · Architecture

---

Run Claude Code (Anthropic's AI coding CLI) in Docker sandboxes with organization-managed team profiles and git worktree support.

SCC isolates AI execution in containers, enforces branch safety, and prevents destructive git commands. Organizations distribute plugins through a central config—developers get standardized setups without manual configuration.

Plugin Marketplace: Extend Claude with the official plugin marketplace. Start with scc-safety-net to block destructive git commands like push --force.

30-Second Guide

Requires: Python 3.10+, Docker Desktop 4.50+, Git 2.30+

pip install scc-cli      # Install
scc setup                # Configure (paste your org URL, pick your team)
cd ~/project && scc      # Auto-detect workspace and launch (or scc start ~/project)

Run scc doctor to verify your environment or troubleshoot issues.

Smart Start Flow

When you run scc or scc start:

• Auto-detects workspace from git repository root or .scc.yaml location
• Shows Quick Resume if you have recent sessions for this workspace
• Prints brief context (workspace root, entry directory, team) before launching
• Safety guard: Won't auto-launch from suspicious directories (home, /tmp). Explicit paths like scc start ~/ prompt for confirmation

Keyboard shortcuts in interactive mode:

• Enter — Select/resume session
• n — Start new session
• Esc — Go back
• q — Quit

---

Find Your Path

You are...	Start here
Developer joining a team	Developer Onboarding — what you get automatically
Team Lead setting up your team	Team Setup — manage plugins in your own repo
Org Admin configuring security	Organization Setup — control what's allowed org-wide
Exploring plugins	Plugin Marketplace — official plugins & safety tools

---

Developer Onboarding

New to a team? After running scc setup and scc start, you get:

• Your team's approved plugins and MCP servers — pre-configured and ready
• Organization security policies — applied automatically, no action needed
• Command guardrails — block destructive git commands like push --force (when scc-safety-net plugin is enabled)
• Isolated git worktrees — your main branch stays clean while Claude experiments

What you never need to do:

• Edit config files manually
• Download or configure plugins
• Worry about security settings

Your org admin and team lead handle the configuration. You just code.

---

Who Controls What

Setting	Org Admin	Team Lead	Developer
Block dangerous plugins/servers	✅ Sets	❌ Cannot override	❌ Cannot override
Default plugins for all teams	✅ Sets	—	—
Team-specific plugins	✅ Approves	✅ Chooses	—
Project-local config (.scc.yaml)	✅ Can restrict	✅ Can restrict	✅ Extends
Safety-net policy (block/warn)	✅ Sets	❌ Cannot override	❌ Cannot override

Organization security blocks cannot be overridden by teams or developers.

"Approves" = teams can only select from org-allowed marketplaces; blocks always apply. "Extends" = can add plugins/settings, cannot remove org defaults.

---

Organization Setup

Org admins create a single JSON config that controls security for all teams:

{
  "schema_version": "1.0.0",
  "organization": { "name": "Acme Corp", "id": "acme" },
  "marketplaces": {
    "sandboxed-code-official": {
      "source": "github",
      "owner": "CCimen",
      "repo": "sandboxed-code-plugins"
    }
  },
  "security": {
    "blocked_plugins": ["*malicious*"],
    "blocked_mcp_servers": ["*.untrusted.com"],
    "safety_net": { "action": "block" }
  },
  "defaults": {
    "allowed_plugins": ["*"],
    "network_policy": "unrestricted"
  },
  "profiles": {
    "backend": { "additional_plugins": ["scc-safety-net@sandboxed-code-official"] },
    "frontend": { "additional_plugins": ["scc-safety-net@sandboxed-code-official"] }
  }
}

Host this anywhere: GitHub, GitLab, S3, or any HTTPS URL. Private repos work with token auth.

See examples/ for complete org configs and GOVERNANCE.md for delegation rules.

---

Team Setup

Teams can manage their plugins two ways:

Option A: Inline (simple) — Team config lives in the org config file.

"profiles": {
  "backend": {
    "additional_plugins": ["scc-safety-net@sandboxed-code-official"]
  }
}

Option B: Team Repo (GitOps) — Team maintains their own config repo.

"profiles": {
  "backend": {
    "config_source": {
      "source": "github",
      "owner": "acme",
      "repo": "backend-team-scc-config"
    }
  }
}

With Option B, team leads can update plugins via PRs to their own repo—no org admin approval needed for allowed additions.

Config precedence: Org defaults → Team profile → Project .scc.yaml (additive merge; blocks apply after merge).

---

Commands

Essential Commands

Command	Description
scc	Smart start: auto-detect workspace, show Quick Resume, or launch
scc setup	Configure organization connection
scc doctor	Check system health and diagnose issues
scc stop	Stop running sandbox(es)

Session & Team

Command	Description
scc start --resume	Resume most recent session
scc start --select	Pick from recent sessions
scc team switch	Switch to a different team profile
scc sessions	List recent sessions

Worktrees

Command	Description
scc worktree create <repo> <name>	Create git worktree for parallel development
scc worktree enter [target]	Enter worktree in subshell (no shell config needed)
scc worktree list -v	List worktrees with git status

Governance & Admin

Command	Description
scc config explain	Show effective config with sources
scc exceptions list	View active exceptions
scc audit plugins	Audit installed plugins
scc support bundle	Generate support bundle for troubleshooting

Run scc <command> --help for options. See CLI Reference for the complete command list (40+ commands).

Git Worktrees

Primary method (no shell config needed):

scc worktree enter feature-auth   # Opens a subshell in the worktree
# Type 'exit' to return to your previous directory

Power users: Add this shell wrapper for seamless cd switching:

# Add to ~/.bashrc or ~/.zshrc
wt() {
  local p
  p="$(scc worktree switch "$@")" || return $?
  cd "$p" || return 1
}

Usage examples (both methods):

scc worktree enter ^        # Enter main branch worktree
scc worktree enter -        # Enter previous worktree (like cd -)
wt feature-auth             # Switch with shell wrapper
wt scc/feature-x            # Match by full branch name

Note: Branch names with / are sanitized to - (e.g., feature/auth → feature-auth).

Status indicators in list -v:

Symbol	Meaning
+N	N staged files
!N	N modified files
?N	N untracked files
.	Clean worktree
…	Status timed out

Cleanup stale entries:

scc worktree prune -n   # Dry-run: show what would be pruned
scc worktree prune      # Actually prune stale entries

---

Configuration

Setup Modes

Organization mode (recommended):

scc setup
# Enter URL when prompted: https://gitlab.example.org/devops/scc-config.json

Standalone mode (no org config):

scc setup --standalone

Project Config

Add .scc.yaml to your repository root for project-specific settings:

additional_plugins:
  - "project-linter@internal"

session:
  timeout_hours: 4

File Locations

~/.config/scc/config.json    # Org URL, team, preferences
~/.cache/scc/                # Cache (safe to delete)
<repo>/.scc.yaml             # Project-specific config

---

Troubleshooting

Run scc doctor to diagnose issues.

Problem	Solution
Docker not reachable	Start Docker Desktop
Organization config fetch failed	Check URL and token
Plugin blocked	Check scc config explain for security blocks

See TROUBLESHOOTING.md for more solutions.

---

Documentation

• CLI Reference — complete command reference (40+ commands)
• Architecture — system design, module structure
• Governance — delegation model, security boundaries
• Marketplace — plugin distribution and safety-net
• Troubleshooting — common problems and solutions
• Examples — ready-to-use organization config templates

---

Automation & CI

SCC supports non-interactive operation for CI/CD pipelines and scripting.

# CI pipeline example
scc start --non-interactive --team backend ~/project

# Preview configuration as JSON
scc start --dry-run --json

# Full automation mode
scc start --dry-run --json --non-interactive ~/project

Key flags:

• --non-interactive — Fail fast instead of prompting
• --json — Machine-readable output with standardized envelope
• --dry-run — Preview configuration without launching

Exit codes: 0 (success), 2 (usage error), 3 (config error), 4 (tool error), 5 (prerequisites), 6 (governance block), 130 (cancelled)

See CLI Reference → Exit Codes for complete documentation.

---

Development

uv sync              # Install dependencies
uv run pytest        # Run tests
uv run ruff check    # Run linter

---

License

MIT