sanduk 0.1.0__tar.gz

sanduk-0.1.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Nothing is released yet; everything below is unreleased initial work.
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- `sanduk`: build a Linux VM through Apple `container`, run Claude Code headless in it against a bind-mounted directory, collect `REPORT.md`, delete the container. `--dry-run` prints the command instead.
+
+- `--proxy`: run the agent on an `--internal` network with no route off the host, and relay its API calls through a host-side proxy that holds the key. The container gets a per-run token. Chosen over passing the key in as an environment variable because the container otherwise has a live credential and unrestricted egress, which makes "sandbox" true of the filesystem only. The relay is not optional overhead: on an egress-blocked network it is the container's only path to the API, so it must exist regardless, and injecting the key there costs two lines.
+
+- `--allow-model` and `--max-tokens-cap`: model allowlist and token ceiling applied to request bodies at the relay. Enforced on the host, where the container cannot edit them, which is the point of doing it here rather than in the agent's flags.
+
+- `tests/test_script.py` compares every function, method, and constant the standalone script and the package share, normalized for annotations and docstrings. Pinning the Containerfile alone was not enough: three relay fixes had landed in the package and not in the script, one of them a bodyless GET being dropped with no response. Eight names differ by design -- `die` against `AgentboxError`, `util.note`, and typing -- and are listed in the test; anything else fails it.
+
+- `python3` in the agent image. Two runs in a row reached their verdict by hand-tracing rather than execution -- once against C with no compiler, once against a Python file with no interpreter -- and each spent turns discovering the absence before working around it. With an interpreter present the agent ports the file, runs it, and marks findings reproduced. Shipping a toolchain for every language the agent might meet is unbounded; one interpreter covers the common workload. It is not free: execution buys more turns, not fewer.
+
+- Per-request token counts on the relay's log line: `in=`, `cache_write=`, `cache_read=`, `out=`. Both response shapes are read, because Claude Code sends `stream=false` and the API also streams: server-sent events carry usage in `message_start` and `message_delta`, a JSON body carries it once at the top level. Only SSE lines holding `"usage"` are parsed, so a stream is still forwarded chunk by chunk; a JSON body is buffered to 256KB and parsed at the end, since nothing in it can be read until it is whole. The request digest under `--log-bodies` gained `stream=` so the two are told apart without guessing. A `/v1/messages` response that yields no counts logs `usage=?` rather than a line that looks ordinary. Answers what the end-of-run total cannot: how much of each turn was a cache read, and so whether a second container reuses the first one's cached prefix.
+
+- `--log-bodies`: record every request body the agent sends upstream. A digest line per call plus full JSON under `--log-dir`, which defaults outside the bind mount so the agent cannot read or edit its own audit trail. Bodies carry the system prompt and the contents of every file read, so they are written to files rather than to the terminal.
+
+- Preflight validation of `ANTHROPIC_API_KEY` against the real endpoint before any container is created. A bad key inside the container costs 174s of SDK retry backoff before failing; the preflight rejects it in 0.27s.
+
+- Preflight warning when the macOS application firewall has the running interpreter set to "Block incoming connections". That configuration drops the container's connection to the relay with no error, so the first API call hangs until `--timeout`. The check reads `socketfilterfw --listapps`, matches the framework `Resources/Python.app` path that `sys.executable` does not resolve to, and prints the exact `--unblockapp` command.
+
+- `Makefile` and a pytest suite: 54 fast tests using a local fake upstream, 7 integration tests that boot real VMs. Neither makes an API call, so `make test` costs nothing and needs no key.
+
+### Changed
+
+- `sanduk.py` is now the `sanduk` package under `src/`, installed as an `sanduk` console script. The 762-line script had one module for the CLI, the relay, the Apple `container` calls, and the Claude Code flags, which is exactly the shape that makes a second container engine or a second agent an edit through the middle of it. The pre-package script is kept at `scripts/sanduk.py`, which still runs standalone through its PEP 723 header. It now embeds the Containerfile as a raw string and writes it to a temporary build context when `--containerfile` is absent, so a copied script needs nothing beside it; an explicit `--containerfile` that is missing is still an error rather than a silent fall back. `tests/test_script.py` keeps the embedded copy byte-identical to `sanduk/resources/Containerfile`.
+
+- Every call to a container engine moved behind `runtime.Runtime`, with `AppleContainer` the only implementation. `ContainerSpec` describes a container to run and `run_argv` renders it, so the placeholder container and the agent container go through the same code. A Docker or Podman subclass has to supply four things: the CLI name, the delete verb (`rm`, not `delete`), how `network inspect` reports the gateway, and whether the host bridge needs a placeholder container at all. Neither engine is installed here, so neither is written -- an untested backend is worse than an absent one.
+
+- The Containerfile ships as package data at `sanduk/resources/Containerfile`, and `--containerfile` defaults to it. Previously the default was the string `"Containerfile"`, resolved against the working directory, so the tool only built an image when run from a checkout.
+
+- `die()` became `AgentboxError`, and `main` returns an exit code instead of raising `SystemExit`. Library code that calls `sys.exit` cannot be embedded. The timeout path benefits directly: teardown caught `except SystemExit` and so also caught any unrelated `sys.exit` on the way out; it now catches the one exception it means.
+
+- One Makefile. The packaging frontend and the container frontend both defined `build`, `rebuild`, `test`, and `clean` with different meanings. Image targets are now `image` and `image-rebuild`; `build` is the Python one; `clean` deletes containers and build artifacts; `distclean` adds the resolved environment, `destroy` adds the image, network, and logs. Help is generated from `##` comments rather than a hand-maintained echo list that drifts.
+
+- pytest, ruff, and mypy configuration consolidated into `pyproject.toml`; `pytest.ini` deleted. Both files declared `testpaths`, and `pytest.ini` silently won.
+
+- `requires-python` raised to 3.11, matching what the PEP 723 header already declared.
+
+- Merged `keyproxy.py` into `sanduk.py`. The relay had no second consumer and no CLI of its own, and the split made `sanduk.py` fail with `ModuleNotFoundError` the moment it was copied anywhere without its sibling. Absolute-path and symlink invocation both happened to work, which is what made the failure easy to miss.
+
+- The relay binds the network's bridge gateway rather than `0.0.0.0`. The wildcard bind put it on Wi-Fi and LAN as well. Because vmnet only creates the bridge while a container is attached, a placeholder container now holds the network up long enough to bind, and is torn down with the run.
+
+- Dropped the relay's peer-subnet check. Once bound to the gateway it admitted the only caller class the bind does not already exclude: a host process reaching `192.168.128.1` presents source IP `192.168.128.1`, which is inside the subnet. Access control is the run token alone.
+
+- The task prompt is no longer written to `TASK.md` on the mount. The agent found its own instructions there as a file and spent two of six turns identifying them, and pointing `-w` at a real repository dropped a file into it. The prompt already arrives via `-p`.
+
+- Both scripts declare their interpreter with PEP 723 and `uv run --script`.
+
+### Fixed
+
+- `scripts/agentbox.py` is `scripts/sanduk.py`. The rename to sanduk changed the file's contents but not its name, and `tests/test_script.py` finds it by path, so both drift tests skipped with the reason `scripts/ is not in this tree` -- which was false. The two tests that exist to catch a stale embedded Containerfile were themselves silently disabled.
+
+- `--proxy`: the relay now offers only `gzip` upstream, for clients that already accept it. The API answers in brotli whenever a client lists it, Claude Code's does, and no standard-library module decodes brotli -- so the token counts above read compressed bytes and silently found nothing. Narrowing the offer keeps the response compressed and decodable; adding a brotli dependency to read a log line was the alternative. A client that asked for `identity`, or for something else entirely, still gets what it asked for.
+
+- `--proxy`: a request with no body -- any GET, including `/v1/models`, which is on the default allowlist -- was dropped with the connection closed and no response. `apply_policy` returned the body it was given and `relay` read `None` back as "refused", so "there is nothing to check" and "this was rejected" were the same value. The refusal is now a separate flag. Every GET the suite covered stopped at a 401 or 403, so nothing reached the path that conflated them.
+
+- Path allowlist matches `urlsplit(path).path` exactly instead of by prefix. Prefix matching admitted `/v1/models-internal-secret`; matching the raw path would have rejected `/v1/messages?beta=true`, which is what Claude Code actually calls. Both cases now have tests.
+
+- The relay reads upstream with `read1`. `read(n)` blocks until `n` bytes arrive, which stalled every server-sent event behind a 64KB buffer.
+
+- `--timeout` is enforced by a timer, not by a deadline checked inside the response loop. An agent that hangs without printing produces no lines, so the loop-checked deadline never fired.
+
+- Teardown catches `SystemExit` as well as `KeyboardInterrupt`. A timeout kill exits through `die()` and previously skipped the delete, leaving a container alive holding the key.
+
+- `validate_key` runs before the placeholder container is started. A rejected key used to leak that container.
+
+- The token summary counts `cache_creation_input_tokens` and `cache_read_input_tokens`. A run billed at $0.23 was reported as 10 input tokens; 74% of its input was cache reads.
+
+- `make clean` no longer deletes `sanduk-logs`. Recorded request bodies are evidence, not scratch; they move to `make destroy`, which reports the file count.
+
+- `make destroy` is idempotent and no longer prints `Error 1 (ignored)` when the image or network is already gone.
+
+- `make run` quotes `$(TASK)`. The default task is five words and was being split into five positional arguments.

sanduk-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2026 Shakeeb Alireza
+
+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.

sanduk-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.3
+Name: sanduk
+Version: 0.1.0
+Summary: Run an agent inside a disposable container
+Keywords: agent,claude,container,sandbox,proxy
+Author: Shakeeb Alireza
+Author-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# sanduk
+
+Run an agent inside a disposable container. The agent does its work, writes a report to a bind-mounted directory, and the container is deleted.
+
+Today that means Claude Code on macOS through Apple's [`container`](https://github.com/apple/container). The container engine sits behind `sanduk.runtime.Runtime` and the agent CLI behind `sanduk.agent`, so Docker, Podman, and other agents are additive.
+
+In its stronger mode the VM has no route off the host and never holds the API key: a host-side relay injects the credential, and the container gets a per-run token that is worthless anywhere else.
+
+'sanduk' means 'box' in Arabic.
+
+## Requirements
+
+- Mac with Apple silicon, macOS 26 or later (`container` requires both)
+
+- [`container`](https://github.com/apple/container) 1.2.0 or later
+
+- Python 3.11 or later, and `uv`
+
+- An Anthropic API key in `ANTHROPIC_API_KEY`
+
+Apple's `container` runs **Linux** containers as lightweight VMs. There is no such thing as a macOS container here; anything needing Xcode or the macOS toolchain cannot be the workload.
+
+The image is `node:22-slim` plus `git`, `ripgrep`, `curl`, `jq`, and `python3`. The agent can only run what is in it. Without an interpreter it falls back to hand-tracing and still writes a confident report, so check whether the findings say they were reproduced. There is no C, Go, or Rust toolchain: point `--image` at your own, or `--containerfile` at one to build.
+
+## Quickstart
+
+```text
+make sync
+make image
+export ANTHROPIC_API_KEY=sk-ant-...
+make run TASK='Summarise every Python file here.' WORK=./work
+```
+
+Or directly, which is where all the flags live:
+
+```text
+uv run sanduk 'Summarise every Python file here.' -w ./work --proxy
+uv run sanduk --help
+```
+
+## Two modes
+
+|                                   | default          | `--proxy`                        |
+| --------------------------------- | ---------------- | -------------------------------- |
+| Host filesystem                    | VM isolation     | VM isolation                     |
+| API key location                   | inside the VM    | host only; VM holds a run token  |
+| Egress                             | unrestricted     | none                             |
+| Agent can POST your source anywhere| yes              | no                               |
+| Which endpoints the agent may call | all              | three, matched exactly           |
+| Record of what it sent upstream    | none             | `--log-bodies`                   |
+
+The default mode is filesystem isolation and nothing more. `--proxy` is where the containment is.
+
+## How --proxy works
+
+1. `sanduk-net` is created with `--internal`: no route off the host.
+
+2. vmnet only creates the host bridge while a container is attached, so a placeholder container is started first and torn down at the end.
+
+3. The relay binds the bridge gateway only, so it is unreachable from Wi-Fi or LAN.
+
+4. The container is given `ANTHROPIC_BASE_URL` and a per-run token as its `ANTHROPIC_API_KEY`. Both arrive through the child process environment, so neither appears in `ps`, and `container inspect` shows the token, not the key.
+
+5. The relay checks the token, checks the path against an exact allowlist, applies any model or token policy, swaps in the real key, and streams the response back.
+
+6. Every relayed call logs its token counts: `in=`, `cache_write=`, `cache_read=`, `out=`. A `/v1/messages` call that reports none logs `usage=?` rather than a line that looks ordinary. The relay narrows the client's `Accept-Encoding` to `gzip` to read them, because the API answers in brotli whenever a client offers it and nothing in the standard library decodes brotli.
+
+## Flags worth knowing
+
+`--allow-model claude-opus-5` and `--max-tokens-cap N` are enforced on the host, where the container cannot edit them. Claude Code asks for `max_tokens: 64000` on every call, so a cap below that silently truncates every request.
+
+`--log-bodies` records each request body: a digest line per call, full JSON under `--log-dir` (default `./sanduk-logs`, deliberately outside the bind mount so the agent cannot read or edit its own audit trail). Bodies contain the system prompt and every file the agent has read.
+
+`--dry-run` prints the `container run` command and exits. `--keep` leaves the container for inspection, and warns that `container inspect` then exposes the token.
+
+## Layout
+
+```text
+src/sanduk/
+    cli.py         flags, lifecycle, teardown
+    runtime.py     container engines; ContainerSpec; only `apple` is implemented
+    agent.py       the agent CLI inside the container; only Claude Code
+    proxy.py       the host-side relay
+    preflight.py   key validation, macOS firewall check
+    resources/
+        Containerfile
+```
+
+A second engine is a `Runtime` subclass and a `RUNTIMES` entry. It must supply four things: the CLI name, the verb that deletes a container (`rm`, not `delete`), how `network inspect` reports the gateway, and whether the host bridge needs a placeholder container to exist at all.
+
+## Make targets
+
+`make help` lists all of them. The ones you need:
+
+```text
+make sync             Resolve and install the environment
+make test             Fast suite: no containers, no API calls, no key needed
+make test-container   Integration suite: boots real containers
+make test-all         Both
+make qa               lint-check, format-check, typecheck, test
+make image            Build the agent image if missing
+make image-rebuild    Force a rebuild
+make run              TASK='...' WORK=./dir ARGS='--effort max'
+make run-proxy        Same, with no egress and the key held on the host
+make shell            Interactive shell in the image
+make ps / make logs   Containers / recorded request bodies
+make stop             Stop sanduk containers, leave them on disk
+make clean            Delete them and build scratch. Keeps work/ and logs
+make distclean        clean, plus .venv and tool caches
+make destroy          clean, plus the image, the network, and the logs
+make system-start / system-stop / system-status
+```
+
+`make system-stop` stops Apple's container service for everything on the machine, not just sanduk.
+
+## Testing
+
+The fast suite makes no API calls and needs no key: the relay is exercised against a local fake upstream, and the preflight is monkeypatched. `scripts/sanduk.py` carries its own copy of the relay, so a test compares every function the two share and fails on any difference outside a listed set of architectural ones. The integration suite boots real VMs and proves the relay by the 401 an invalid key earns from the real endpoint, which is itself proof the request arrived.
+
+## Measured on this setup
+
+| | |
+| --- | --- |
+| Bad key, host preflight | 0.27s |
+| Bad key, no preflight | 174s of in-container retry backoff |
+| Agent run, 3 files, 7 turns | 35.4s wall, 23.2s of it upstream |
+| Review of one 59-line file, 10 turns | $0.55, 148s wall |
+| Claude Code's system prompt and tool schemas | 22,993 tokens |
+| That prefix written cold, as a share of one run | 25% of its cost |
+| The same prefix on a second run inside the cache TTL | read, not written: 23% cheaper |
+| Container direct egress on `sanduk-net` | `000` |
+| Real key present in container environment | 0 occurrences |
+
+## Known traps
+
+The macOS application firewall silently drops connections to a binary set to "Block incoming connections", so the agent's first API call hangs until `--timeout` rather than failing. Homebrew's Python is shipped blocked on at least one machine; uv's interpreters are signed and auto-allowed. `--proxy` runs a preflight that names the exact `socketfilterfw --unblockapp` command when it sees an explicit block. It cannot detect an interpreter that will merely prompt.
+
+`AF_UNIX` paths cap at 104 bytes on macOS, which matters if you point `--log-dir` somewhere deep.

sanduk-0.1.0/README.md

@@ -0,0 +1,138 @@
+# sanduk
+
+Run an agent inside a disposable container. The agent does its work, writes a report to a bind-mounted directory, and the container is deleted.
+
+Today that means Claude Code on macOS through Apple's [`container`](https://github.com/apple/container). The container engine sits behind `sanduk.runtime.Runtime` and the agent CLI behind `sanduk.agent`, so Docker, Podman, and other agents are additive.
+
+In its stronger mode the VM has no route off the host and never holds the API key: a host-side relay injects the credential, and the container gets a per-run token that is worthless anywhere else.
+
+'sanduk' means 'box' in Arabic.
+
+## Requirements
+
+- Mac with Apple silicon, macOS 26 or later (`container` requires both)
+
+- [`container`](https://github.com/apple/container) 1.2.0 or later
+
+- Python 3.11 or later, and `uv`
+
+- An Anthropic API key in `ANTHROPIC_API_KEY`
+
+Apple's `container` runs **Linux** containers as lightweight VMs. There is no such thing as a macOS container here; anything needing Xcode or the macOS toolchain cannot be the workload.
+
+The image is `node:22-slim` plus `git`, `ripgrep`, `curl`, `jq`, and `python3`. The agent can only run what is in it. Without an interpreter it falls back to hand-tracing and still writes a confident report, so check whether the findings say they were reproduced. There is no C, Go, or Rust toolchain: point `--image` at your own, or `--containerfile` at one to build.
+
+## Quickstart
+
+```text
+make sync
+make image
+export ANTHROPIC_API_KEY=sk-ant-...
+make run TASK='Summarise every Python file here.' WORK=./work
+```
+
+Or directly, which is where all the flags live:
+
+```text
+uv run sanduk 'Summarise every Python file here.' -w ./work --proxy
+uv run sanduk --help
+```
+
+## Two modes
+
+|                                   | default          | `--proxy`                        |
+| --------------------------------- | ---------------- | -------------------------------- |
+| Host filesystem                    | VM isolation     | VM isolation                     |
+| API key location                   | inside the VM    | host only; VM holds a run token  |
+| Egress                             | unrestricted     | none                             |
+| Agent can POST your source anywhere| yes              | no                               |
+| Which endpoints the agent may call | all              | three, matched exactly           |
+| Record of what it sent upstream    | none             | `--log-bodies`                   |
+
+The default mode is filesystem isolation and nothing more. `--proxy` is where the containment is.
+
+## How --proxy works
+
+1. `sanduk-net` is created with `--internal`: no route off the host.
+
+2. vmnet only creates the host bridge while a container is attached, so a placeholder container is started first and torn down at the end.
+
+3. The relay binds the bridge gateway only, so it is unreachable from Wi-Fi or LAN.
+
+4. The container is given `ANTHROPIC_BASE_URL` and a per-run token as its `ANTHROPIC_API_KEY`. Both arrive through the child process environment, so neither appears in `ps`, and `container inspect` shows the token, not the key.
+
+5. The relay checks the token, checks the path against an exact allowlist, applies any model or token policy, swaps in the real key, and streams the response back.
+
+6. Every relayed call logs its token counts: `in=`, `cache_write=`, `cache_read=`, `out=`. A `/v1/messages` call that reports none logs `usage=?` rather than a line that looks ordinary. The relay narrows the client's `Accept-Encoding` to `gzip` to read them, because the API answers in brotli whenever a client offers it and nothing in the standard library decodes brotli.
+
+## Flags worth knowing
+
+`--allow-model claude-opus-5` and `--max-tokens-cap N` are enforced on the host, where the container cannot edit them. Claude Code asks for `max_tokens: 64000` on every call, so a cap below that silently truncates every request.
+
+`--log-bodies` records each request body: a digest line per call, full JSON under `--log-dir` (default `./sanduk-logs`, deliberately outside the bind mount so the agent cannot read or edit its own audit trail). Bodies contain the system prompt and every file the agent has read.
+
+`--dry-run` prints the `container run` command and exits. `--keep` leaves the container for inspection, and warns that `container inspect` then exposes the token.
+
+## Layout
+
+```text
+src/sanduk/
+    cli.py         flags, lifecycle, teardown
+    runtime.py     container engines; ContainerSpec; only `apple` is implemented
+    agent.py       the agent CLI inside the container; only Claude Code
+    proxy.py       the host-side relay
+    preflight.py   key validation, macOS firewall check
+    resources/
+        Containerfile
+```
+
+A second engine is a `Runtime` subclass and a `RUNTIMES` entry. It must supply four things: the CLI name, the verb that deletes a container (`rm`, not `delete`), how `network inspect` reports the gateway, and whether the host bridge needs a placeholder container to exist at all.
+
+## Make targets
+
+`make help` lists all of them. The ones you need:
+
+```text
+make sync             Resolve and install the environment
+make test             Fast suite: no containers, no API calls, no key needed
+make test-container   Integration suite: boots real containers
+make test-all         Both
+make qa               lint-check, format-check, typecheck, test
+make image            Build the agent image if missing
+make image-rebuild    Force a rebuild
+make run              TASK='...' WORK=./dir ARGS='--effort max'
+make run-proxy        Same, with no egress and the key held on the host
+make shell            Interactive shell in the image
+make ps / make logs   Containers / recorded request bodies
+make stop             Stop sanduk containers, leave them on disk
+make clean            Delete them and build scratch. Keeps work/ and logs
+make distclean        clean, plus .venv and tool caches
+make destroy          clean, plus the image, the network, and the logs
+make system-start / system-stop / system-status
+```
+
+`make system-stop` stops Apple's container service for everything on the machine, not just sanduk.
+
+## Testing
+
+The fast suite makes no API calls and needs no key: the relay is exercised against a local fake upstream, and the preflight is monkeypatched. `scripts/sanduk.py` carries its own copy of the relay, so a test compares every function the two share and fails on any difference outside a listed set of architectural ones. The integration suite boots real VMs and proves the relay by the 401 an invalid key earns from the real endpoint, which is itself proof the request arrived.
+
+## Measured on this setup
+
+| | |
+| --- | --- |
+| Bad key, host preflight | 0.27s |
+| Bad key, no preflight | 174s of in-container retry backoff |
+| Agent run, 3 files, 7 turns | 35.4s wall, 23.2s of it upstream |
+| Review of one 59-line file, 10 turns | $0.55, 148s wall |
+| Claude Code's system prompt and tool schemas | 22,993 tokens |
+| That prefix written cold, as a share of one run | 25% of its cost |
+| The same prefix on a second run inside the cache TTL | read, not written: 23% cheaper |
+| Container direct egress on `sanduk-net` | `000` |
+| Real key present in container environment | 0 occurrences |
+
+## Known traps
+
+The macOS application firewall silently drops connections to a binary set to "Block incoming connections", so the agent's first API call hangs until `--timeout` rather than failing. Homebrew's Python is shipped blocked on at least one machine; uv's interpreters are signed and auto-allowed. `--proxy` runs a preflight that names the exact `socketfilterfw --unblockapp` command when it sees an explicit block. It cannot detect an interpreter that will merely prompt.
+
+`AF_UNIX` paths cap at 104 bytes on macOS, which matters if you point `--log-dir` somewhere deep.

sanduk-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "sanduk"
+version = "0.1.0"
+description = "Run an agent inside a disposable container"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = [
+    "agent",
+    "claude",
+    "container",
+    "sandbox",
+    "proxy",
+]
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Typing :: Typed",
+]
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "Shakeeb Alireza"
+email = "shakfu@users.noreply.github.com"
+
+[project.scripts]
+sanduk = "sanduk.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.6",
+    "twine>=7.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "sanduk"
+module-root = "src"
+source-include = [
+    "tests/**",
+    "CHANGELOG.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not container'"
+markers = ["container: boots real containers; slow, needs the engine running"]
+
+[tool.ruff]
+src = [
+    "src",
+    "tests",
+]
+line-length = 90
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+
+[tool.mypy]
+strict = true

sanduk-0.1.0/pyproject.toml.orig

@@ -0,0 +1,62 @@
+[project]
+name = "sanduk"
+version = "0.1.0"
+description = "Run an agent inside a disposable container"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Shakeeb Alireza", email = "shakfu@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+keywords = ["agent", "claude", "container", "sandbox", "proxy"]
+# This project intentionally has no runtime dependencies.
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+sanduk = "sanduk.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.6",
+    "twine>=7.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "sanduk"
+module-root = "src"
+source-include = ["tests/**", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not container'"
+markers = [
+    "container: boots real containers; slow, needs the engine running",
+]
+
+[tool.ruff]
+src = ["src", "tests"]
+line-length = 90
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true

sanduk-0.1.0/src/sanduk/__init__.py

@@ -0,0 +1,25 @@
+"""Run an agent in a disposable container.
+
+The agent works in a bind-mounted directory, writes a report, and the container
+is deleted. With --proxy it runs on a network with no route off the host and
+never holds the API key: a host-side relay injects the credential and the
+container gets a per-run token.
+"""
+
+from sanduk.agent import KEY_ENV, REPORT_NAME
+from sanduk.cli import main
+from sanduk.errors import AgentboxError
+from sanduk.proxy import start_proxy
+from sanduk.runtime import ContainerSpec, Runtime, get_runtime
+
+__all__ = [
+    "KEY_ENV",
+    "REPORT_NAME",
+    "AgentboxError",
+    "ContainerSpec",
+    "Runtime",
+    "get_runtime",
+    "main",
+    "start_proxy",
+]
+__version__ = "0.1.0"

sanduk-0.1.0/src/sanduk/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m sanduk`."""
+
+import sys
+
+from sanduk.cli import main
+
+sys.exit(main())