Why Sandbox AI Coding Agents

AI coding agents like Claude Code and Codex execute real commands on real systems. This guide explains why sandboxing matters and when it’s essential.

The Reality of AI Code Execution

AI coding agents are powerful because they can:

• Read and write files in your project
• Execute shell commands
• Run git operations
• Install dependencies
• Make API calls

This power comes with responsibility. While agents are designed to be helpful and careful, any system that executes commands can cause unintended effects.

Risks Without Sandboxing

Filesystem Access

Without isolation, the agent can access any file your user account can access:

Accessible	Risk
~/.ssh/	SSH keys for servers and services
~/.aws/	AWS credentials
~/.config/	Application configurations
Other projects	Cross-project contamination

With SCC, the agent only sees the workspace you explicitly mount.

Git History Damage

AI coding sessions involve experimentation. Without guardrails:

Command	Impact
git push --force	Overwrites remote history, affects entire team
git reset --hard	Discards uncommitted work
git branch -D	Force-deletes branches without merge check
git clean -fd	Deletes untracked files permanently

SCC’s built-in safety engine blocks these commands by default (fail-closed). The optional scc-safety-net plugin provides additional coverage via agent-native hooks.

Configuration Drift

When each developer configures their AI agent independently:

• Plugins vary across the team
• Settings differ between machines
• Behavior is inconsistent and hard to debug

SCC provides team profiles that ensure consistent configuration across all developers and providers.

How SCC Sandboxes Agents

Container Isolation

SCC runs agents inside OCI containers using any Docker-compatible runtime (Docker Engine, OrbStack, Colima, or Docker Desktop):

┌─────────────────────────────────┐
│          Host System            │
│  ~/.ssh  ~/.aws  ~/other-work   │
│           ▲                     │
│           │ (blocked)           │
│  ┌────────┴────────────────┐    │
│  │   Container Sandbox     │    │
│  │  /workspace (mounted)   │    │
│  │  Agent runs here        │    │
│  └─────────────────────────┘    │
└─────────────────────────────────┘

The agent can only access /workspace — your mounted project directory.

Built-in Safety Engine

SCC includes a fail-closed safety engine inside every container:

• Shell tokenizer — parses compound commands to catch destructive operations
• Git safety rules — blocks force push, hard reset, branch force delete, etc.
• Network tool interception — wraps curl, wget, ssh, scp, sftp, rsync
• Fail-closed — if policy cannot be loaded, all guarded commands are blocked

The optional scc-safety-net plugin adds extra agent-native coverage where supported. Today that plugin is Claude-focused; Codex support is planned.

Network Topology Enforcement

When network_policy is web-egress-enforced:

• The agent container runs on an internal-only Docker network
• A Squid proxy sidecar is the sole gateway to the internet
• The proxy enforces an ACL for HTTP/HTTPS traffic
• Default deny rules block loopback, private CIDRs, link-local ranges, and cloud metadata endpoints before any allow rules
• The agent physically cannot bypass the proxy — this is topology enforcement, not just env vars

Caution

A container is not a network boundary by itself. If you care about what the agent can reach on your network, focus on web-egress-enforced or locked-down-web, not just “runs in a container.”

Provider Choice Without Rebuilding Governance

Different teams adopt AI coding tools differently. One team may prefer Claude for exploratory work. Another may prefer Codex for backend-heavy tasks. SCC lets organizations allow Claude, Codex, or both without rebuilding the governance model for each provider.

That means:

• one org config and policy model
• one onboarding flow
• one set of network and safety controls
• freedom to choose the provider that fits the task

Blast Radius Reduction

Without Sandbox	With SCC
Could affect entire system	Limited to mounted workspace
Could damage git history	Safety engine blocks destructive commands
Could install anything	Only approved plugins
Inconsistent recovery	Worktrees provide clean rollback

When Sandboxing Is Essential

Enterprise Environments

• Multiple teams sharing AI tools across providers
• Compliance requirements
• Need for audit trails
• Consistent security posture

Sensitive Codebases

• Financial or healthcare systems
• Code with embedded secrets
• Production infrastructure

Team Adoption

• Onboarding new developers
• Standardizing AI tool usage across Claude Code and Codex
• Reducing support burden from inconsistent setups

When Sandboxing May Be Optional

Solo Development

Individual developers with full system backups, git remotes, and understanding of the risks.

Quick Experiments

One-off tests where no sensitive data is involved and results are disposable.

Note

Even in these cases, sandboxing provides peace of mind. SCC’s overhead is minimal once set up.

Getting Started

uv tool install scc-cli    # Install
scc setup                  # Configure org, connect providers
scc start ~/your-project   # Launch sandboxed

Next Steps

Quick Start Install and try SCC

Security Model Deep dive into isolation layers, safety engine, and network enforcement

Architecture Provider-neutral design and container images