Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ Versioning after its first public release.

### Added

- A zero-build, responsive GitHub Pages homepage under `docs/` that presents the
measured benchmark, fail-closed boundary, kubeadm quickstart, and architecture
without depending on another repository or third-party frontend assets.
- Standalone local gVisor environment, Python SDK, CLI, stdio MCP, and operator Console
surfaces for the first public release candidate.
- `make destroy-local`, a KUBECONFIG-aware Makefile, and resource checks in `make doctor`.
Expand Down Expand Up @@ -98,6 +101,9 @@ Versioning after its first public release.

### Fixed

- The new-profile doctor gate now reflects the default 6 GiB VM and sparse disk's
measured physical footprint (6.5 GiB available memory / 25 GiB free disk), so a
capable host is not rejected solely by the virtual disk's 60 GiB maximum size.
- Findings of the 2026-09-02 pre-release review, in four groups. Control plane:
request handling, admission and readiness defects found by reading the API
and store paths. Lifecycle: Runtime, workspace and checkpoint state transitions
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[Website](https://hullwork.github.io/sandbox/) · [Documentation](docs/README.md) · [Benchmark report](docs/BENCHMARK_REPORT_2026-09-01.md)

**Run an agent's shell and file operations inside a gVisor Pod on your own
Kubernetes cluster.** A Control Plane owns Workspaces, quotas and credentials.
Agents reach it through a Python SDK, the `sandbox` CLI, or a stdio MCP bridge —
Expand Down Expand Up @@ -48,7 +50,7 @@ operation fails; it never falls back to running on the host.

```bash
make bootstrap # create .venv and install SDK + test dependencies
make test # 834 unit and contract tests, no network, no cluster
make test # 839 unit and contract tests, no network, no cluster
make verify # complete Python, Console, manifest, Helm, wheel gate
make help # every Make target with its one-line description
```
Expand Down Expand Up @@ -200,8 +202,8 @@ it first rather than discovering a gap halfway through the VM build.
| Python | 3.11 or newer |
| Host OS | macOS or Linux |
| Host architecture | amd64 or arm64 (`scripts/local-cluster.yaml` pins Ubuntu images for both; gVisor is installed for `x86_64` and `aarch64`) |
| **Available memory** | **8 GiB free** for a new profile — a hard check, not a warning |
| **Free disk** | **35 GiB free** under `$LIMA_HOME` (default `~/.lima`) for a new profile — also a hard check |
| **Available memory** | **6.5 GiB free** for a new profile — the default VM reserves 6 GiB; this is a hard check, not a warning |
| **Free disk** | **25 GiB free** under `$LIMA_HOME` (default `~/.lima`) for a new profile — the 60 GiB VM disk is sparse; this is also a hard check |
| Virtualization | On Linux, a readable and writable `/dev/kvm`. Without it Lima falls back to QEMU TCG software emulation, which boots kubeadm many times slower and is not usable in practice. `make doctor` warns rather than fails on this one. |
| Network | Egress to pull the Ubuntu cloud image, Kubernetes apt packages, Cilium, gVisor, Metrics Server, and Rook/Ceph images |

Expand Down
1 change: 1 addition & 0 deletions docs/.nojekyll
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@

28 changes: 28 additions & 0 deletions docs/404.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="theme-color" content="#07090d" />
<title>Not found · Sandbox Platform</title>
<link rel="icon" href="./assets/sandbox-mark.svg" type="image/svg+xml" />
<link rel="stylesheet" href="./assets/site.css" />
<style>
main { min-height: 100vh; display: grid; place-items: center; padding: 32px; text-align: center; }
.error-code { color: #a7ff83; font: 12px ui-monospace, monospace; letter-spacing: .15em; }
h1 { margin: 20px 0; font-size: clamp(52px, 10vw, 96px); }
p { max-width: 500px; margin: 0 auto 30px; color: #9aa7a3; font-size: 18px; line-height: 1.6; }
</style>
</head>
<body>
<main>
<div>
<img src="./assets/sandbox-mark.svg" alt="" width="64" height="64" />
<div class="error-code">RUNTIME_NOT_FOUND · 404</div>
<h1>Outside the sandbox.</h1>
<p>This route does not exist. The good news: nothing fell back to the host.</p>
<a class="button primary" href="./">Return to safety <span aria-hidden="true">→</span></a>
</div>
</main>
</body>
</html>
2 changes: 1 addition & 1 deletion docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ proof. It records phase timing and outcome in
`.sandbox/quickstart-summary.json`. Use `make up-local` directly when the Python
environment is already prepared and only the deployment needs updating.

For a new profile, `make doctor` fails when less than 8 GiB of memory or 35 GiB
For a new profile, `make doctor` fails when less than 6.5 GiB of memory or 25 GiB
of disk is free. When the dedicated `sandbox-local` VM already exists, it uses a
2 GiB memory / 5 GiB disk reuse gate instead. It
warns when `/dev/kvm` is absent on Linux (Lima then falls back to QEMU software
Expand Down
4 changes: 4 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

Sandbox Platform provides an execution-as-a-service boundary for agents: a Control Plane, gVisor Runtime, workspace volume services, official Python SDK, and MCP bridge. Start with the [README](../README.md), then use the documents below.

The project homepage is the zero-build static site in [index.html](index.html).
GitHub Pages serves this directory from `main:/docs`; assets stay repository-local
so the public site has no runtime dependency on a separate project or frontend build.

| Document | Audience | Use it for |
| --- | --- | --- |
| [README](../README.md) | All users | Product scope, quick start, architecture summary, and current status |
Expand Down
4 changes: 2 additions & 2 deletions docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ export KUBECONFIG="$PWD/.sandbox/kubeconfig"
## `make doctor` cannot reach Docker or reports insufficient capacity

**Symptom.** The first quickstart phase stops before creating a VM because the
Docker daemon is unreachable, available memory is below 8 GiB, or free space under
`$LIMA_HOME` is below 35 GiB for a new profile. Reusing an existing `sandbox-local`
Docker daemon is unreachable, available memory is below 6.5 GiB, or free space under
`$LIMA_HOME` is below 25 GiB for a new profile. Reusing an existing `sandbox-local`
profile lowers the capacity gate to 2 GiB memory and 5 GiB disk.

**Fix.** On macOS, start Docker Desktop (`open -a Docker`) and wait until it is
Expand Down
13 changes: 13 additions & 0 deletions docs/assets/sandbox-mark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading