project-sandbox 0.1.2__tar.gz

project_sandbox-0.1.2/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.dist/
+build/
+dist/
+.venv/
+.project-sandbox/
+.uv-cache
+.uv_cache
+.pycache-test
+.pytest_cache
+.uv-python
+.claude/worktrees
+.agents
+.claude/skills
+# project-sandbox — do not commit agent secrets
+.devcontainer/
+# release state tracking
+.release-status/

project_sandbox-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Peter Krusche, 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

project_sandbox-0.1.2/PKG-INFO

@@ -0,0 +1,96 @@
+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).

project_sandbox-0.1.2/README.md

@@ -0,0 +1,86 @@
+# 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).

project_sandbox-0.1.2/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "project-sandbox"
+version = "0.1.2"
+description = "Sandbox coding agents inside isolated container runtimes."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "jinja2==3.1.6",
+]
+
+[dependency-groups]
+dev = [
+    "pytest==9.1.1",
+    "ruff==0.16.1",
+]
+
+[project.scripts]
+project-sandbox = "project_sandbox.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/project_sandbox"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/project_sandbox",
+    "/LICENSE",
+    "/README.md",
+    "/pyproject.toml",
+]
+
+[tool.uv]
+cache-dir = ".uv_cache"
+
+[tool.ruff.lint.per-file-ignores]
+# Registry payload validation reports malformed external data, not bad caller types.
+"scripts/update-pins.py" = ["TRY004"]
+# Keeping resource-owning contexts nested makes their cleanup boundaries explicit.
+"tests/*.py" = ["SIM117"]

project_sandbox-0.1.2/src/project_sandbox/__init__.py

@@ -0,0 +1,10 @@
+"""project-sandbox package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("project-sandbox")
+except PackageNotFoundError:
+    __version__ = "unknown"

project_sandbox-0.1.2/src/project_sandbox/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

project_sandbox-0.1.2/src/project_sandbox/build_cache.py

@@ -0,0 +1,78 @@
+"""Input fingerprinting so a matching image can be reused without rebuilding.
+
+The CLI rebuilds the container image on every run by default. When the build
+inputs have not changed and the image still exists, that work is wasted. This
+module computes a deterministic fingerprint of the build inputs and records it,
+alongside the image tag, in a sidecar JSON file under the generated
+``.project-sandbox`` directory. The caller compares the current fingerprint with
+the recorded one (and confirms the image still exists) to decide whether the
+build can be skipped.
+
+Skipping is correctness-safe: it only happens on an exact fingerprint+tag match,
+and any read/parse problem degrades to "not cached" so the build runs.
+"""
+
+import hashlib
+import json
+from pathlib import Path
+
+# Top-level files in the generated context that fully determine the CLI image.
+# The CLI always builds context_dir/"Dockerfile"; entrypoint.sh, init-firewall.sh
+# and project-sandbox-devcontainer-init are COPY'd into it.
+_BUILD_INPUT_FILES = (
+    "Dockerfile",
+    "entrypoint.sh",
+    "init-firewall.sh",
+    "project-sandbox-devcontainer-init",
+)
+
+_STATE_FILENAME = ".build-state.json"
+
+
+def state_path(context_dir: Path) -> Path:
+    return context_dir / _STATE_FILENAME
+
+
+def compute_fingerprint(context_dir: Path, *, extra: dict[str, str]) -> str:
+    """Return a SHA256 over the build-input files plus the ``extra`` mapping.
+
+    ``extra`` carries inputs that are not files in ``context_dir`` (the resolved
+    base image and the image tag). Missing input files are simply skipped, so
+    the fingerprint still reflects which files are present.
+    """
+    h = hashlib.sha256()
+    for name in sorted(_BUILD_INPUT_FILES):
+        path = context_dir / name
+        if not path.is_file():
+            continue
+        h.update(name.encode("utf-8"))
+        h.update(b"\0")
+        h.update(hashlib.sha256(path.read_bytes()).hexdigest().encode("ascii"))
+        h.update(b"\0")
+    h.update(b"extra\0")
+    h.update(json.dumps(extra, sort_keys=True, separators=(",", ":")).encode("utf-8"))
+    return h.hexdigest()
+
+
+def read_state(context_dir: Path) -> dict | None:
+    try:
+        data = json.loads(state_path(context_dir).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def write_state(context_dir: Path, *, image_tag: str, fingerprint: str) -> None:
+    state_path(context_dir).write_text(
+        json.dumps({"image_tag": image_tag, "fingerprint": fingerprint}) + "\n",
+        encoding="utf-8",
+    )
+
+
+def is_cache_valid(context_dir: Path, *, image_tag: str, fingerprint: str) -> bool:
+    state = read_state(context_dir)
+    return (
+        state is not None
+        and state.get("image_tag") == image_tag
+        and state.get("fingerprint") == fingerprint
+    )

project_sandbox-0.1.2/src/project_sandbox/chroot.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from . import templating
+
+
+def render(context_dir: Path) -> Path:
+    out = context_dir / "chroot-run.sh"
+    out.write_text(
+        templating.get_template("chroot-run.sh.j2").render() + "\n", encoding="utf-8"
+    )
+    out.chmod(0o700)
+    return out