Metadata-Version: 2.4
Name: project-sandbox
Version: 0.1.2
Summary: Sandbox coding agents inside isolated container runtimes.
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: jinja2==3.1.6
Description-Content-Type: text/markdown

# project-sandbox

[![PyPI](https://img.shields.io/pypi/v/project-sandbox.svg)](https://pypi.org/project/project-sandbox/)

`project-sandbox` runs Claude Code, Codex CLI, OpenCode, Pi, or a plain Bash shell
inside per-project Linux containers. On macOS, direct CLI runs default to Apple's
[`container`](https://github.com/apple/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.
* **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:

```bash
uv tool install project-sandbox
project-sandbox --help
```

Or run directly from PyPI without installing:

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

From a source checkout:

```bash
uv sync
uv run project-sandbox --help
```

Generate sandbox files for a project:

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

Preview every action without writing files or starting a runtime:

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

Start an agent in the sandbox:

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

Build on top of an existing project Dockerfile:

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

## Documentation

- [Documentation index](https://github.com/pkrusche/project-sandbox/tree/main/docs)
- [Usage guide](https://github.com/pkrusche/project-sandbox/blob/main/docs/usage.md)
- [Generated files and runtime behavior](https://github.com/pkrusche/project-sandbox/blob/main/docs/runtime.md)
- [Security model](https://github.com/pkrusche/project-sandbox/blob/main/docs/security.md)
- [Development guide](https://github.com/pkrusche/project-sandbox/blob/main/docs/development.md)
- [References and related projects](https://github.com/pkrusche/project-sandbox/blob/main/docs/references.md)

## License

MIT. See [LICENSE](LICENSE).
