Foundry Sandbox
Ephemeral, batteries-included Docker workspaces that isolate AI coding agents from your credentials and host system.
What It Does
Foundry Sandbox runs your code and AI assistants inside ephemeral Docker containers where credentials never enter the sandbox. A unified proxy on the host holds your real API keys and tokens, injecting them into outbound requests only after policy validation. Code running inside — whether an AI assistant, a build script, or a malicious dependency — never sees the actual credentials.
+------------------+ +------------------------------+ +------------------+
| Sandbox | | Unified Proxy | | External APIs |
| | | | | |
| AI assistants, |---->| API gateways (per-provider) |---->| GitHub, Claude, |
| build scripts, | | Network allowlist (Squid) | | OpenAI, Gemini |
| your code | | Git policy engine | | |
| | | | | |
| [no real creds] | | [all credentials] | | |
+------------------+ +------------------------------+ +------------------+
Multiple independent security layers provide defense in depth:
| Layer | What it does |
|---|---|
| Credential isolation | API keys never enter the container; injected by proxy on egress |
| Read-only filesystem | Prevents destructive commands (rm -rf / is a no-op) |
| Network allowlists | Egress restricted to approved domains only |
| Branch isolation | Each sandbox sees only its own branch; other branches are hidden |
| Git safety | Protected branches, force-push blocking, GitHub API controls |
Each sandbox is a git worktree — create one in seconds, destroy it with zero trace.
Key Features
Security
- Credential isolation via unified proxy (enabled by default)
- Network control: allowlist, host-only, or no network
- Branch isolation and git safety policies
Developer experience
- Claude Code, Gemini CLI, and Codex CLI are pre-installed
- Fast creation: worktrees share git objects, new sandboxes spin up in seconds
- Presets and history: save configurations, repeat last command with
cast repeat - Spec-driven development: foundry-mcp server pre-configured for Claude Code
Automation
- Volume mounts (read-write or read-only)
- All commands support
--jsonfor scripting
Quick Start
1. Install
curl -fsSL https://raw.githubusercontent.com/foundry-works/foundry-sandbox/main/install.sh | bash
Clones to ~/.foundry-sandbox, adds the cast command, enables tab completion, and builds the Docker image. Also available on PyPI (pipx install foundry-sandbox). See Getting Started for manual install, uninstall, and prerequisites.
2. Set up credentials
claude setup-token # Claude Code
codex login # Codex CLI (ChatGPT subscription)
gh auth login # GitHub (for private repos and push)
gemini auth # Gemini CLI (if using)
Credentials stay on the host — the proxy injects them into requests so they never enter the sandbox. See Configuration for all supported API keys.
3. Create a sandbox
Use the guided wizard to create a new sandbox.
cast new
4. Work inside
Launch your favorite AI agent.
claude # Claude Code
gemini # Gemini CLI
codex # Codex CLI
4. Commit, push
Ask your AI agent to commit and push changes.
5. Destroy
CTRL+D to exit the sandbox, then from host:
cast destroy <sandbox-name> --yes # Remove worktree and container
Prerequisites
Docker 20.10+, Git 2.x+, Bash 4+, tmux 3+, Python 3.10+. Linux and macOS supported natively; Windows requires WSL2. macOS ships Bash 3.2 — install 4+ via brew install bash.
Limitations
- Not a targeted-attack boundary — defends against supply-chain attacks and AI mistakes, not a determined human attacker with host-level Docker access
- Requires Docker — no native process isolation
- Linux/macOS — Windows requires WSL2
- No GPU passthrough — needs additional Docker configuration
Documentation
| Document | Description |
|---|---|
| Getting Started | Installation and first sandbox |
| Commands | Full command reference |
| Workflows | Common patterns and recipes |
| Configuration | API keys, plugins, and config files |
| Architecture | Technical design and diagrams |
| Security Model | Threat model, defenses, and hardening |
| Operations | Proxy operations runbook |
| Observability | Metrics and debugging |
| Contributing | For contributors |
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
License
MIT License. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for foundry-sandbox 0.20.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| foundry_sandbox-0.20.15.tar.gz | 753.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| foundry_sandbox-0.20.15-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 920.9 kB
Release files / foundry_sandbox-0.20.15.tar.gz
| Download URL | foundry_sandbox-0.20.15.tar.gz |
|---|---|
| Size | 753.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
121b59f933e2ccd10ef6e3434c9ade1f3661a8a22adf8b32b6c1c0e5728e4a22
|
|
BLAKE2b-256 checksum How to use checksums |
47bf177128141e77355fd71cf3e029e1cf309ce38247854ef8464a90945b3884
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 28, 2026.
Transparency logRelease files / foundry_sandbox-0.20.15-py3-none-any.whl
| Download URL | foundry_sandbox-0.20.15-py3-none-any.whl |
|---|---|
| Size | 167.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2409b8e37417a10da8575407d5342d9342a99ea8ec531dde285ff62b9da74dd2
|
|
BLAKE2b-256 checksum How to use checksums |
93d222cd4360ce9f8b6823f74f98158f88065847d84e0aa3532f58d10b946053
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 28, 2026.
Transparency log
