SCC - Sandboxed Claude CLI

Quick Start · Commands · Documentation · Configuration · Architecture

📚 Full Documentation: scc-cli.dev

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+

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

Alternative: pip install scc-cli works if you don't have uv.

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
Applies personal profile (if saved) after team config, before workspace overrides
Bypass mode enabled: Permission prompts are skipped by default since the Docker sandbox already provides isolation. This does not prevent access to files inside the mounted workspace. Press Shift+Tab inside Claude to toggle permissions back on if needed
Safety guard: Won't auto-launch from suspicious directories (home, /tmp). Explicit paths like scc start ~/ prompt for confirmation

Keyboard shortcuts in dashboard:

↑↓ — Navigate list
Enter — Open action menu (containers/sessions/worktrees)
Tab — Switch between tabs
n — Start new session
t — Switch team
p — Profile quick menu (save/apply/diff)
r — Refresh
s — Settings & maintenance
? — Help
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
Personal profiles (optional) — save your own plugin/MCP preferences per project

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
Personal profiles (local)	✅ Governed by security blocks	✅ Governed by delegation	✅ Chooses
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.

Enforcement Scope (v1)

SCC enforces org-managed plugins and MCP servers at runtime.
MCP servers in repo .mcp.json or plugin bundles are outside SCC enforcement scope (block the plugin to restrict).
network_policy is partially enforced (proxy env injection + MCP suppression under isolated), not a full egress firewall.
session.auto_resume is advisory only in v1.

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 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).

Personal Profiles

Want your own plugins or MCP servers without committing anything? Personal profiles are per‑project, stored outside the repo, and auto‑applied on scc start.

If you install plugins inside the container and they only show up in sandbox settings, scc profile save and scc profile status will detect them and offer to import them into .claude/settings.local.json before saving.

# Save current workspace preferences
scc profile save

# Apply or preview
scc profile apply
scc profile apply --preview

# Check status/drift
scc profile status

TUI Integration: Press p in the dashboard or go to Settings → Profiles for visual profile management:

Save/Apply/Diff profiles without CLI commands
Sync profiles overlay for export/import to a local folder
Import preview shows what will change before applying

Sync across machines:

# Via TUI: Settings → Profiles → Sync profiles
# Or via CLI with git operations:
scc profile export --repo ~/dotfiles/scc-profiles --commit --push
scc profile sync --repo ~/dotfiles/scc-profiles --pull --commit --push

Note: TUI sync writes files locally only (no git). Use CLI flags --commit --push for git operations.

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

Personal Profiles

Command	Description
`scc profile save`	Save current workspace settings as a personal profile
`scc profile apply`	Apply profile to current workspace
`scc profile diff`	Show diff between profile and workspace
`scc profile status`	Show whether a profile exists and if drift is detected
`scc profile export --repo PATH`	Export profiles to a local repo
`scc profile import --repo PATH`	Import profiles from a local repo
`scc profile sync --repo PATH`	Pull/import + export + optional commit/push

Maintenance

Command	Description
`scc reset`	Interactive maintenance hub (cache, sessions, config)
`scc reset --cache`	Clear cache files
`scc reset --sessions`	Prune old sessions (keeps recent 20)
`scc reset --all`	Factory reset (removes all SCC data)
`scc config paths`	Show file locations and sizes
`scc sessions prune`	Clean up old sessions

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
`scc completion bash`	Generate shell completions (bash/zsh/fish)

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

Run scc config paths to see all locations with sizes and permissions.

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 Guide for more solutions.

Documentation

Visit scc-cli.dev for comprehensive documentation:

Getting Started — installation and first steps
CLI Reference — complete command reference (40+ commands)
Architecture — system design, module structure
Governance — delegation model, security boundaries
Plugin 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

Name		Name	Last commit message	Last commit date
Latest commit History 347 Commits
.github/workflows		.github/workflows
examples		examples
homebrew		homebrew
scripts		scripts
src/scc_cli		src/scc_cli
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SCC - Sandboxed Claude CLI

30-Second Guide

Smart Start Flow

Find Your Path

Developer Onboarding

Who Controls What

Enforcement Scope (v1)

Organization Setup

Team Setup

Personal Profiles

Commands

Essential Commands

Session & Team

Worktrees

Personal Profiles

Maintenance

Governance & Admin

Git Worktrees

Configuration

Setup Modes

Project Config

File Locations

Troubleshooting

Documentation

Automation & CI

Development

License

About

Uh oh!

Releases 27

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

SCC - Sandboxed Claude CLI

30-Second Guide

Smart Start Flow

Find Your Path

Developer Onboarding

Who Controls What

Enforcement Scope (v1)

Organization Setup

Team Setup

Personal Profiles

Commands

Essential Commands

Session & Team

Worktrees

Personal Profiles

Maintenance

Governance & Admin

Git Worktrees

Configuration

Setup Modes

Project Config

File Locations

Troubleshooting

Documentation

Automation & CI

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 27

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages