Surfaces
| surface | use it for | entry point |
|---|---|---|
| Demo portal | human debugging | /ui/ opens shell, files, browser, VS Code, VNC, and RDP tabs against live sandboxes. |
| Admin dashboard | operator view | /admin/ shows feature receipts, health probes, active machines, pool state, lifecycle events, snapshots, metrics, and action buttons. |
| E2B-compatible API | SDK drop-in | Python, Node, Go, OpenAI Agents, and E2B Code Interpreter shaped demos use the same gateway and envd routes. |
| CLI | scripts and ops | coppice covers lifecycle, exec, logs, templates, pools, snapshots, volumes, signing, auth, and machine access helpers. |
| MCP | agent tools | coppice-mcp exposes create/list/kill and filesystem/command primitives to MCP clients without a bespoke integration. |
Compute choices
Pick the isolation boundary by template. Jail templates are fastest and share the FreeBSD kernel. bhyve templates run full guest kernels for Linux, Windows, GPU passthrough, and cases where a VM boundary matters.
| template shape | backend | what you get |
|---|---|---|
python | VNET jail | Fast create, shell/files/envd, package install, browserless code execution, snapshots, forks, volumes, air-gap, metrics, and logs. |
browser | VNET jail | Chromium via CDP proxy for automation, screenshots, and browser-agent work. |
vscode | VNET jail | code-server through /vscode-proxy/:id/, useful when a human needs a full editor in the sandbox. |
desktop | VNET jail | openbox, Firefox, xterm, xclock, xeyes, VNC, RDP, clipboard buttons, Ctrl-Alt-Del, and adaptive resize. |
| Linux bhyve | VM pool | Debian cloud-image guests with SSH-backed shell/exec and warm checkout through the bhyve pool controller. |
| Windows bhyve | VM console | Windows Server eval guests through the bhyve framebuffer and VNC console path. |
| GPU bhyve | Linux VM + passthrough | NVIDIA passthrough via ppt(4); receipt requires in-guest nvidia-smi and ends with GPU_OK. |
State and data
- TTL and AutoResume. Sandboxes can kill or pause on timeout. AutoResume wakes paused jail and bhyve SSH sessions when the SDK, CLI, files, shell, or envd paths touch them again.
- Snapshots and forks. Durable snapshots capture a ZFS filesystem fork point. Forking creates a fresh sandbox with the same filesystem state and a new lifecycle.
- Persistent volumes. Volumes are ZFS datasets mounted into sandboxes with nullfs. The registry prevents deleting a volume that is still mounted.
- Directory snapshots. Subtree snapshots create tar + SHA-256 artifacts for a specific path, then restore that artifact into another directory.
- Template authoring. OCI imports, template reload, template build jobs, and snapshot signing cover the BYOI path for FreeBSD-compatible jail images. bhyve templates use image files plus sidecar metadata.
Security and operations
- Network isolation. Each jail gets its own VNET epair, IPv4/IPv6 addresses, and source-IP-scoped pf anchor. Air-gap mode denies new outbound flows and kills existing pf states on policy flip.
- Auth, quotas, audit. Optional API keys map to tenant IDs and scopes. Tenant quotas gate create before backend work starts, and mutating/error decisions are written to the audit ring.
- Secrets. The secrets store injects selected values as env vars; the credential proxy keeps upstream credentials on the host and gives the sandbox only a proxy token.
- Observability. Prometheus metrics, per-sandbox resource samples, logs, lifecycle events, webhooks, template build logs, and OpenTelemetry spans are all exposed by the gateway.
- Receipts. Bench rigs write transcripts under
benchmarks/results/. The admin page and appendices link claims back to those receipts.
Known open work
The remaining gaps are not hidden. The short list is competitor-gaps plus the row-level feature audit: Capsicum wrapping for envd, multi-node overlay, rootless bhyve, object-store bucket mounts/archive, GPU memory checkpointing, and production UX polish around tenant key issuance.