Container/microVM sandbox for coding agents — supervised or headless sessions, credential & network isolation, git/jj workspace integration: project-sandbox runs Claude Code, Codex CLI, OpenCode, Pi, GitHub Copilot CLI, or a plain Bash shell
inside per-project Linux containers. On macOS, direct CLI runs default to Apple's
container runtime, where each container
runs in its own VM. On Linux, direct CLI runs support Docker or Podman.
⚠️ Created with the help of AI.
🚧 Experimental work in progress
‼️ Use at your own risk.
Many sandboxes exist - this is the one with a feature-set / configureable agency-boundary that I was comfortable with in the end:
- Strong isolation - on OSX with Apple Container VMs. Custom Dockerfile support (as long as it's based on Debian)
- Agent config glue: Forward host credentials / agent subscriptions into containers selectively, update settings to bypass permissions inside the container.
- Devcontainer support: Creates a matched devcontainer config for editor support (weaker isolation but integrated workflow).
- Unsupervised job runs - submit batch jobs.
- Network access restrictions: restrict to allowed domains, (somewhat) hardened firewall script, or opt into the global Squid egress sidecar for one hostname-based policy, managed with
project-sandbox-egress. - git/jj integration: Managed execution with worktrees / workspaces. No credentials to push inside containers.
- pinned dependencies: pre-install agents & extra tools into the image, manual upversioning.
- Simple workflow (in my view).
- Minimal dependencies (jinja2)
Install from PyPI:
uv tool install project-sandbox
project-sandbox --helpOr run directly from PyPI without installing:
uvx project-sandbox --help
uvx project-sandbox /absolute/path/to/repo python:3.12-slimFrom a source checkout:
uv sync
uv run project-sandbox --helpCheck host prerequisites (container runtimes, git/jj):
project-sandbox doctorGenerate sandbox files for a project:
project-sandbox /absolute/path/to/repo python:3.12-slimPreview every action without writing files or starting a runtime:
project-sandbox --dry-run /absolute/path/to/repo python:3.12-slimStart an agent in the sandbox:
project-sandbox --agent codex /absolute/path/to/repo python:3.12-slimBuild on top of an existing project Dockerfile:
project-sandbox /absolute/path/to/repo --dockerfile /absolute/path/to/repo/DockerfileWeb projects can use --node-npm with any supported agent or Bash shell
(see Node.js + npm projects and
Headless browser testing):
project-sandbox --node-npm --agent claude /absolute/path/to/repo- Usage guide
- Agent proxy setup and security
- Egress sidecar and
project-sandbox-egress - Runtimes
- Generated files and runtime behavior
- Security model
- Development guide
- References and related projects
- Changelog
- Roadmap and future work
MIT. See LICENSE.