{"id":41182730,"url":"https://github.com/foundry-works/foundry-sandbox","last_synced_at":"2026-03-01T01:03:35.322Z","repository":{"id":333365583,"uuid":"1136880463","full_name":"foundry-works/foundry-sandbox","owner":"foundry-works","description":"Ephemeral Docker workspaces that isolate AI coding agents from your credentials and host system.","archived":false,"fork":false,"pushed_at":"2026-02-25T21:49:15.000Z","size":2941,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T00:41:28.330Z","etag":null,"topics":["ai-agents","ai-coding","autonomous-agents","claude-code","codex","gemini","sandbox-environment","security-tools","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foundry-works.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/security-model.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-18T14:30:15.000Z","updated_at":"2026-02-25T21:49:14.000Z","dependencies_parsed_at":"2026-02-26T00:03:35.057Z","dependency_job_id":null,"html_url":"https://github.com/foundry-works/foundry-sandbox","commit_stats":null,"previous_names":["foundry-works/foundry-sandbox"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/foundry-works/foundry-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundry-works%2Ffoundry-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundry-works%2Ffoundry-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundry-works%2Ffoundry-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundry-works%2Ffoundry-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foundry-works","download_url":"https://codeload.github.com/foundry-works/foundry-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundry-works%2Ffoundry-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29957128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T22:53:01.873Z","status":"ssl_error","status_checked_at":"2026-02-28T22:52:50.699Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","autonomous-agents","claude-code","codex","gemini","sandbox-environment","security-tools","spec-driven-development"],"created_at":"2026-01-22T20:12:06.657Z","updated_at":"2026-03-01T01:03:35.296Z","avatar_url":"https://github.com/foundry-works.png","language":"Python","readme":"# Foundry Sandbox\n\n[![CI](https://github.com/foundry-works/foundry-sandbox/actions/workflows/test.yml/badge.svg)](https://github.com/foundry-works/foundry-sandbox/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/foundry-sandbox)](https://pypi.org/project/foundry-sandbox/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Built for Claude Code](https://img.shields.io/badge/Built_for-Claude_Code-cc785c)](https://docs.anthropic.com/en/docs/claude-code)\n\nEphemeral Docker workspaces that isolate AI coding agents from your credentials and host system.\n\n## What It Does\n\nFoundry 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.\n\n```\n+------------------+     +------------------------------+     +------------------+\n|    Sandbox       |     |       Unified Proxy          |     |  External APIs   |\n|                  |     |                              |     |                  |\n|  AI assistants,  |----\u003e|  API gateways (per-provider) |----\u003e|  GitHub, Claude, |\n|  build scripts,  |     |  Network allowlist (Squid)   |     |  OpenAI, Gemini  |\n|  your code       |     |  Git policy engine           |     |                  |\n|                  |     |                              |     |                  |\n|  [no real creds] |     |  [all credentials]           |     |                  |\n+------------------+     +------------------------------+     +------------------+\n```\n\nMultiple independent security layers provide defense in depth:\n\n| Layer | What it does |\n|-------|-------------|\n| Credential isolation | API keys never enter the container; injected by proxy on egress |\n| Read-only filesystem | Prevents destructive commands (`rm -rf /` is a no-op) |\n| Network allowlists | Egress restricted to approved domains only |\n| Branch isolation | Each sandbox sees only its own branch; other branches are hidden |\n| Git safety | Protected branches, force-push blocking, GitHub API controls |\n\nEach sandbox is a git worktree — create one in seconds, destroy it with zero trace.\n\n## Key Features\n\n**Security**\n- Credential isolation via unified proxy (enabled by default)\n- Network control: allowlist, host-only, or no network\n- Branch isolation and git safety policies\n\n**Developer experience**\n- Claude Code, Gemini CLI, and Codex CLI are pre-installed\n- Fast creation: worktrees share git objects, new sandboxes spin up in seconds\n- Presets and history: save configurations, repeat last command with `cast repeat`\n- Spec-driven development: [foundry-mcp](https://github.com/foundry-works/claude-foundry) server pre-configured for Claude Code\n\n**Automation**\n- Volume mounts (read-write or read-only)\n- All commands support `--json` for scripting\n\n## Quick Start\n\n**1. Install**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/foundry-works/foundry-sandbox/main/install.sh | bash\n```\n\nClones to `~/.foundry-sandbox`, adds the `cast` command, enables tab completion, and builds the Docker image. Also available on [PyPI](https://pypi.org/project/foundry-sandbox/) (`pipx install foundry-sandbox`). See [Getting Started](docs/getting-started.md) for manual install, uninstall, and prerequisites.\n\n**2. Set up credentials**\n\n```bash\nclaude setup-token              # Claude Code\ncodex login                     # Codex CLI (ChatGPT subscription)\ngh auth login                   # GitHub (for private repos and push)\ngemini auth                     # Gemini CLI (if using)\n```\n\nCredentials stay on the host — the proxy injects them into requests so they never enter the sandbox. See [Configuration](docs/configuration.md) for all supported API keys.\n\n**3. Create a sandbox**\n\nUse the guided wizard to create a new sandbox.\n\n```bash\ncast new\n```\n\n**4. Work inside**\n\nLaunch your favorite AI agent.\n\n```bash\nclaude              # Claude Code\ngemini              # Gemini CLI\ncodex               # Codex CLI\n```\n\n**4. Commit, push**\n\nAsk your AI agent to commit and push changes.\n\n**5. Destroy**\n\nCTRL+D to exit the sandbox, then from host:\n\n```bash\ncast destroy \u003csandbox-name\u003e --yes   # Remove worktree and container\n```\n\n## Prerequisites\n\nDocker 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`.\n\n## Limitations\n\n- **Not a targeted-attack boundary** — defends against supply-chain attacks and AI mistakes, not a determined human attacker with host-level Docker access\n- **Requires Docker** — no native process isolation\n- **Linux/macOS** — Windows requires WSL2\n- **No GPU passthrough** — needs additional Docker configuration\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Getting Started](docs/getting-started.md) | Installation and first sandbox |\n| [Commands](docs/usage/commands.md) | Full command reference |\n| [Workflows](docs/usage/workflows.md) | Common patterns and recipes |\n| [Configuration](docs/configuration.md) | API keys, plugins, and config files |\n| [Architecture](docs/architecture.md) | Technical design and diagrams |\n| [Security Model](docs/security/security-model.md) | Threat model, defenses, and hardening |\n| [Operations](docs/operations.md) | Proxy operations runbook |\n| [Observability](docs/observability.md) | Metrics and debugging |\n| [Contributing](docs/development/contributing.md) | For contributors |\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/foundry-works/foundry-sandbox/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/foundry-works/foundry-sandbox/discussions)\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundry-works%2Ffoundry-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoundry-works%2Ffoundry-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundry-works%2Ffoundry-sandbox/lists"}