Skip to content

About

Container/microVM sandbox for coding agents — supervised or headless sessions, credential and network isolation, git/jj workspace integration

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

project-sandbox

PyPI

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.

Main features

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)

Quick Start

Install from PyPI:

uv tool install project-sandbox
project-sandbox --help

Or run directly from PyPI without installing:

uvx project-sandbox --help
uvx project-sandbox /absolute/path/to/repo python:3.12-slim

From a source checkout:

uv sync
uv run project-sandbox --help

Check host prerequisites (container runtimes, git/jj):

project-sandbox doctor

Generate sandbox files for a project:

project-sandbox /absolute/path/to/repo python:3.12-slim

Preview every action without writing files or starting a runtime:

project-sandbox --dry-run /absolute/path/to/repo python:3.12-slim

Start an agent in the sandbox:

project-sandbox --agent codex /absolute/path/to/repo python:3.12-slim

Build on top of an existing project Dockerfile:

project-sandbox /absolute/path/to/repo --dockerfile /absolute/path/to/repo/Dockerfile

Web 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

Documentation

License

MIT. See LICENSE.

About

Container/microVM sandbox for coding agents — supervised or headless sessions, credential and network isolation, git/jj workspace integration

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages