bot-bottle/docs/research/agent-sandbox-landscape.md

# Landscape: AI-agent sandbox tools

A broader survey than [`landscape-containerized-claude.md`](landscape-containerized-claude.md),
which focused on Claude-Code-specific containerizers. This one covers
general AI-agent sandbox / containment projects — some Claude-specific,
some agent-agnostic, some hosted SaaS — and contrasts them with
bot-bottle's design.

Research conducted 2026-05-11. CubeSandbox added 2026-07-18 (see its
per-project note and the addendum at the end). Also updated 2026-07-18:
bot-bottle no longer uses **pipelock** — outbound DLP is now bot-bottle's
own (deliberately simple) egress scanner (a mitmproxy addon with custom
detectors, PRD 0017 / 0053), and git-push secret scanning is handled by
**gitleaks** in the git-gate. "pipelock" below has been replaced with the
current mechanism; it survives only in older PRDs as history.

## Summary

Nine projects surveyed. None duplicate bot-bottle's combination of
local VM-per-bottle isolation (Firecracker microVM on KVM Linux, Apple
Container on macOS — Docker is now only the legacy fallback), a
declarative JSON manifest, per-agent egress allowlist + outbound-content
DLP via bot-bottle's own egress scanner (plus gitleaks secret-scanning on
git push), and bottle/agent split. Two clusters stand out:

- **Closest neighbours** — agent-safehouse and litterbox: local,
  single-user, thin wrappers over an existing OS primitive
  (`sandbox-exec`, Podman + Landlock).
- **Different category** — tilde.run (hosted SaaS), boxlite and
  microsandbox (microVM libraries for platform builders), CubeSandbox
  (self-hosted multi-tenant microVM service), endo-familiar
  (capability-security paradigm, no OS isolation).

The microVM cluster (matchlock, smolmachines, boxlite, microsandbox,
CubeSandbox) is the most relevant for the v2 isolation discussion in
[`stronger-isolation-alternatives.md`](stronger-isolation-alternatives.md):
libkrun and Apple's Virtualization.framework have made local microVMs
ergonomic enough that microVMs are **now bot-bottle's default backend**
(Firecracker on KVM Linux, Apple Container on macOS), with Docker kept
only as a legacy fallback for CI / hosts without KVM or Apple Container.
That discussion has since shipped, not just been theorized.

**The one that matters most for positioning is CubeSandbox** — it is the
first surveyed project to ship bot-bottle's would-be wedge (default-deny
egress allowlist + full audit logs + in-flight credential custody so keys
never enter the sandbox) *combined with* per-sandbox microVM isolation,
open-source under Apache 2.0, with Tencent Cloud behind it and 10.4k
stars. It's a self-hosted multi-tenant service for platform builders, not
a single-user declarative tool, so it doesn't collide head-on — but it
narrows the "nobody else bundles egress custody + credential injection"
claim that the monetization positioning leans on. See the addendum.

## Per-project notes

### endo-familiar
- **Source**: https://dcfoundation.io/containing-ai-agents-the-endo-familiar-demo/ ; https://github.com/endojs/endo
- **License**: Apache 2.0
- **Isolation**: Object-capability runtime in Hardened JavaScript. Not
  OS-level — agents simply cannot reference resources they were not
  handed.
- **Locality**: Local / decentralized; WebSocket relay for capability
  sharing across machines.
- **Agent integration**: Agent-agnostic, demo only.
- **Config**: Programmatic capability passing; "pet name" system for
  human-readable capability handles.
- **Network policy**: Capability model is the policy; no allowlist or
  firewall.
- **Maturity**: Research demo, Foresight Institute grant. Production use
  of `endo` is via Agoric and MetaMask, not as a containment tool.

### litterbox
- **Source**: https://litterbox.work/ ; https://github.com/Gerharddc/litterbox
- **License**: Apache 2.0 (~66 stars)
- **Isolation**: Podman container on Linux + Wayland socket forwarding;
  optional Landlock LSM for filesystem restriction.
- **Locality**: Local, Linux only.
- **Agent integration**: Generic dev sandbox; works with any agent that
  runs inside the container.
- **Config**: Interactive CLI wizard — `define` (Dockerfile template),
  `build` (prompts), `start` (launch).
- **Network policy**: "Limited isolation by default" — no strict
  allowlist documented.
- **Notable**: Per-key SSH agent confirmation dialogs.
- **Maturity**: Early-stage, ~66 stars.

### agent-safehouse
- **Source**: https://agent-safehouse.dev/ ; https://github.com/eugene1g/agent-safehouse
- **License**: Apache 2.0 (~1,400 stars)
- **Isolation**: macOS `sandbox-exec` (Seatbelt) profiles — kernel-level
  syscall interception, no container.
- **Locality**: Local, macOS only.
- **Agent integration**: Explicit multi-agent wrapper — Claude Code,
  OpenAI Codex, Gemini CLI, Cline, Aider. Usage:
  `safehouse claude --dangerously-skip-permissions`.
- **Config**: Shell functions or custom `sandbox-exec` profile files;
  LLM-assisted profile generation supported.
- **Network policy**: Not addressed.
- **Maturity**: Active through March 2026.

### matchlock
- **Source**: https://github.com/jingkaihe/matchlock
- **License**: MIT (~574 stars, v0.2.10)
- **Isolation**: MicroVMs — Firecracker on Linux, Apple
  Virtualization.framework on macOS. Transparent proxy via nftables DNAT
  (Linux) or gVisor userspace TCP/IP (macOS).
- **Locality**: Local (Homebrew, .deb, .rpm).
- **Agent integration**: Agent-agnostic; SDK examples for Anthropic
  Claude API and OpenAI. Go, Python, TypeScript SDKs.
- **Config**: CLI flags (`--allow-host`, `--secret`, `--no-network`) or
  SDK builder pattern. No manifest file.
- **Network policy**: Default-deny + per-host allowlist.
- **Notable**: Secrets injected in-flight by the host proxy — they never
  enter the VM.
- **Maturity**: Marked experimental.

### tilde.run
- **Source**: https://tilde.run/
- **License**: Proprietary, hosted SaaS.
- **Isolation**: Cloud-hosted containers; underlying mechanism not
  publicly stated (unverified whether OCI containers or microVMs).
- **Locality**: Hosted only.
- **Agent integration**: Claude orchestration explicit; CLI
  (`tilde exec`) and Python SDK; plain-English agent instructions.
- **Config**: DSL for RBAC policies (allow / deny / require human
  approval per action, per repo, per agent).
- **Network policy**: Default-deny with per-request logging; cloud
  metadata endpoints and private networks blocked.
- **Persistence**: All changes versioned and rollback-able via lakeFS;
  atomic commits per run.
- **Maturity**: Private preview, © 2025, built by the lakeFS team.

### boxlite
- **Source**: https://boxlite.ai/ ; https://github.com/boxlite-ai/boxlite
- **License**: Apache 2.0 (~4,700 stars, YC-backed)
- **Isolation**: MicroVMs with dedicated Linux kernel per box — KVM on
  Linux, Hypervisor.framework on macOS. Not containers/namespaces.
- **Locality**: Local, no daemon.
- **Agent integration**: Explicitly targets AI agents; MCP server
  companion (boxlite-ai/boxlite-mcp). Pivoted from dev environments in
  2025.
- **Config**: SDK only — Python, Node.js, Rust, C; Go pending. No
  declarative manifest.
- **Network policy**: "Isolated Network per VM" — details not public
  *(unverified)*.
- **Notable**: Sub-50ms boot, snapshot / fork / clone of VM state. Self
  description: "the SQLite of sandboxing".
- **Maturity**: Active, YC.

### microsandbox
- **Source**: https://github.com/microsandbox/microsandbox (the
  `superradcompany/microsandbox` URL redirects to the same project).
- **License**: Apache 2.0 (~6,000 stars, YC-backed)
- **Isolation**: MicroVMs via libkrun, OCI-compatible images.
  Sub-100ms boot, rootless, no daemon, embeddable as a library.
- **Locality**: Local.
- **Agent integration**: Explicit Claude Code + Cursor targeting via
  "Agent Skills" packages and an MCP server. Agents can create their own
  sandboxes programmatically.
- **Config**: CLI (`msb`), SDKs (Rust, Python, TypeScript), MCP server.
- **Network policy**: Not detailed in public docs.
- **Maturity**: Beta, breaking changes expected; most-starred project in
  this set.

### smolmachines
- **Source**: https://smolmachines.com/ ; https://github.com/smol-machines/smolvm
- **License**: Apache 2.0 (~3,100 stars)
- **Isolation**: MicroVMs via libkrun — Hypervisor.framework on macOS,
  KVM on Linux. No shared kernel.
- **Locality**: Local, no daemon.
- **Agent integration**: Includes an `AGENTS.md`; designed with coding
  agents in mind but no MCP/Skills turnkey integration.
- **Config**: TOML Smolfiles declaring image, networking, volumes, SSH
  agent access, GPU acceleration. Portable `.smolmachine` files.
- **Network policy**: Off by default; per-host allowlist via
  `--allow-host`.
- **Persistence**: Named machines persistent by default; ephemeral runs
  also supported.
- **Maturity**: Active through April 2026.

### CubeSandbox *(added 2026-07-18)*
- **Source**: https://github.com/TencentCloud/CubeSandbox ;
  HN launch https://news.ycombinator.com/item?id=47863430
- **License**: Apache 2.0 (~10.4k stars). By Tencent Cloud; described as
  "battle-tested, production-ready" infra already running in Tencent
  Cloud. Rust / Go / C.
- **Isolation**: MicroVMs via RustVMM + KVM — "each sandbox gets its own
  Guest OS kernel, no Docker shared-kernel escapes." Hardware-level
  isolation, dedicated kernel per instance.
- **Locality**: Self-hosted, but **server/cluster-oriented**, not a
  single-user local CLI. Deploy guides target PVM cloud VMs, bare metal,
  and dev. A single 96-vCPU host is claimed to run 2,000+ concurrent
  sandboxes.
- **Agent integration**: **Drop-in E2B SDK replacement** (single env-var
  change) — the headline compatibility claim. OpenClaw assistant
  integration; general LLM-code execution. Aimed at platform builders,
  not one developer's laptop.
- **Config**: Programmatic via the E2B-compatible SDK. No declarative
  manifest.
- **Network policy**: This is the striking part — **domain allowlists,
  instant block on unauthorized egress, full audit logs, per-sandbox
  traffic tokens, policy-routing egress**, enforced by an eBPF-based
  virtual switch giving kernel-level network isolation. Closest match yet
  to bot-bottle's own default-deny + per-bottle allowlist egress model.
- **Credentials**: **Credential vault** — agents call external APIs / LLMs
  while "keys never enter the sandbox, model context, or logs." Same
  in-flight-injection idea as matchlock, but productized as a vault.
- **Performance**: <60ms cold start (claimed 2.5–50× faster than
  alternatives), <5MB memory per instance; millisecond snapshot rollback
  is upcoming.
- **Maturity**: Open-sourced July 2026 off production Tencent Cloud use;
  most-starred project in this set (~10.4k).

## Comparison table

| Axis | bot-bottle | endo-familiar | litterbox | agent-safehouse | matchlock | tilde.run | boxlite | microsandbox | smolmachines | CubeSandbox |
|---|---|---|---|---|---|---|---|---|---|---|
| Isolation | MicroVM per bottle default (Firecracker/KVM on Linux, Apple Container on macOS) + own egress DLP scanner; Docker legacy fallback, gVisor there if present | Object-capability (no OS isolation) | Podman + opt. Landlock | macOS `sandbox-exec` | MicroVM (Firecracker / Virt.fw) | Hosted container (unverified) | MicroVM (KVM / Hypervisor.fw) | MicroVM (libkrun) | MicroVM (libkrun / KVM) | MicroVM (RustVMM / KVM) |
| Local vs hosted | Local | Local | Local (Linux) | Local (macOS) | Local | Hosted SaaS | Local | Local | Local | Self-hosted (server/cluster) |
| Open source | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | No | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 |
| Agent target | Claude Code | Generic (demo) | Generic | Multi-agent wrapper | Generic (+ Claude/OpenAI SDKs) | Claude focus | Generic | Claude + Cursor (MCP/Skills) | Generic (AGENTS.md) | E2B-compatible (platform builders) |
| Network policy | Default-deny via own egress scanner + per-bottle allowlist + content DLP + gitleaks on git push | Capability model only | Limited | Not addressed | Default-deny + allowlist + secret-injecting proxy | Default-deny + logging | Per-VM net (unverified) | Not documented | Off by default + allowlist | Default-deny allowlist + instant egress block + audit logs + per-sandbox tokens (eBPF) + credential vault |
| Parallel agents | Yes (one bottle per agent) | n/a | Not addressed | One at a time | Multiple VMs | Yes (dashboard) | SDK-level | SDK-level | Architectural | Yes (2,000+/host claimed) |
| Long-running posture | Persistent by default (named, supervised) | n/a (demo) | Session (up while in use) | Per-invocation | Ephemeral VM per run | Per-run (versioned) | Ephemeral + snapshot/fork | Ephemeral / on-demand | Named persistent by default | Ephemeral + auto pause/resume |
| DX: run Claude yolo-style | One command → interactive yolo Claude (`start <agent>`, `--dangerously-skip-permissions` default) | n/a (lib demo) | Wizard + build, then run claude inside (Linux only) | One-command wrapper (`safehouse claude --dangerously-skip-permissions`) | CLI: run a cmd in a VM (not a Claude wrapper) | Hosted (`tilde exec`), not local-native | SDK code required (build the run yourself) | CLI/MCP: sandbox-as-a-tool for the agent, not a wrapper around it | SSH into a named machine, run claude there | Stand up a cluster + drive via E2B SDK |
| Config | JSON manifest (bottles + agents) | Programmatic refs | CLI wizard | Profile files / shell fns | CLI / SDK | DSL + CLI + SDK | SDK | CLI / SDK / MCP | TOML Smolfile | E2B-compatible SDK |
| Maturity | Active May 2026 | Research (2022+) | Early (~66 ⭐) | Active (~1.4k ⭐) | Experimental (~574 ⭐) | Private preview | YC, ~4.7k ⭐ | YC, ~6k ⭐, beta | ~3.1k ⭐ | Tencent, prod, ~10.4k ⭐ |

## What's closest, what's different

**Closest in design and scope.** agent-safehouse and litterbox sit
nearest bot-bottle: local, single-user, thin wrappers over an
existing OS primitive, low-dep. The split is the isolation primitive —
bot-bottle now defaults to a VM per bottle (Firecracker microVM on KVM
Linux, Apple Container on macOS) with its own DLP-scanning egress proxy,
keeping Docker only as a legacy fallback; agent-safehouse uses
`sandbox-exec`; litterbox
uses Podman + Landlock. matchlock and smolmachines are close on *both* the
policy side (default-deny net, per-host allowlist) and — now that
bot-bottle has moved off containers-by-default — the microVM isolation
primitive.

**Solving a different problem.** tilde.run is hosted SaaS for team /
production agent pipelines with data-versioned rollback — explicitly
opposite to bot-bottle's "infrastructure I control" goal. boxlite,
microsandbox, and CubeSandbox are infrastructure libraries/services aimed
at platform builders embedding sandboxes into agent frameworks; they
would be a *backend* bot-bottle could call, not a competitor to its
manifest layer. endo-familiar is in a different paradigm entirely:
capability passing rather than kernel boundaries.

## Borrowable ideas

What bot-bottle already has that the survey suggested as
differentiators:
- Default-deny egress with a per-agent allowlist (own egress scanner).
- DLP scanning of outbound traffic.
- Bottle / agent split (manifest layer above the isolation primitive).
- gVisor auto-detection on Linux.

Ideas worth considering, without abandoning the Python-stdlib-first /
local, single-operator stance:

1. **Per-use SSH key confirmation** (from litterbox). Even with
   KnownHostKey pinning and the egress DLP scanner, a wrapper SSH agent that
   prompts on each key use (e.g. via `osascript` / `notify-send`) would
   catch an agent doing something off-policy with a key it legitimately
   holds. Pure-stdlib, no new deps.
2. **In-flight secret injection** (from matchlock). The egress scanner
   already does allowlisting and DLP; teaching it to *inject* tokens at
   proxy time so e.g. `GITEA_TOKEN` never appears in the container's
   env would close the "agent reads its own env and exfiltrates" path.
   Fits the existing egress-proxy architecture.
3. **MicroVM backend** — ~~on the radar~~ **shipped since this survey.**
   microVMs are now bot-bottle's default (Firecracker on KVM Linux, Apple
   Container on macOS); Docker is the legacy fallback. The libkrun / Apple
   Virtualization.framework ergonomics that microsandbox, smolmachines,
   and matchlock demonstrated turned out to be enough to make it the
   default rather than an opt-in.

Not worth borrowing: the SDK-first programmatic API style of boxlite /
microsandbox (cuts against the declarative-manifest stance), and the
hosted-SaaS dashboard model of tilde.run (cuts against the
"infrastructure I control" goal).

## Caveats

- Star counts and last-commit dates are point-in-time snapshots.
- Several projects' network and persistence behaviour is not
  documented publicly; items so derived are marked *(unverified)*.
- The `superradcompany/microsandbox` URL in the original prompt
  redirects to `microsandbox/microsandbox`; the surveyed project is the
  same.
- CubeSandbox performance/scale numbers (<60ms cold start, <5MB/instance,
  2,000+ sandboxes per 96-vCPU host) are the project's own launch claims,
  not independently verified here.

## Addendum 2026-07-18 — CubeSandbox and the positioning read

CubeSandbox (Tencent Cloud, Apache 2.0, ~10.4k stars, HN launch
[#47863430](https://news.ycombinator.com/item?id=47863430)) is the first
project in this survey to combine, in one open-source stack, everything
bot-bottle treated as its differentiator:

- **Egress custody (connection level)** — default-deny domain allowlist
  (L7 domain/SNI filtering), instant block on unauthorized egress,
  per-sandbox traffic tokens, full audit logs of destinations (eBPF
  virtual switch, "CubeVS"). This matches bot-bottle's egress scanner at
  the *connection level*, productized — see the one thing it does **not**
  match, below.
- **Credential custody** — a vault where keys "never enter the sandbox,
  model context, or logs." This is the in-flight-injection idea from
  matchlock, but as a first-class feature, and it's exactly the
  cross-vendor "egress audit + custody" wedge the monetization
  positioning treats as the one defensible moat.
- **Isolation on par with bot-bottle's current default** — a dedicated
  guest kernel per sandbox (RustVMM/KVM). bot-bottle now defaults to the
  same class of boundary (Firecracker microVM / Apple Container), so this
  is parity, not an edge; CubeSandbox's remaining edge is running that
  per-kernel isolation multi-tenant at scale on one host.

The one axis CubeSandbox does **not** cover — and where bot-bottle stays
distinctive:

- **Content DLP on *authorized* channels.** CubeSandbox's egress control
  is connection-level: it decides *whether* a destination is allowed and
  logs it, and its vault keeps *injected* credentials out of the sandbox
  entirely. Neither inspects the *payload* of traffic to an allowed
  destination. So an agent that exfiltrates over a permitted channel —
  pasting a repo's contents, an agent-derived secret, or PHI into an
  allowed API/domain — is not caught by CubeSandbox. bot-bottle's own
  egress DLP scanner does scan that: response + websocket content against
  the resolved per-flow config, with per-bottle token redaction (see
  recent egress commits). The vault
  approach is arguably *stronger* for the specific case of pre-known
  injected credentials (they can't leak if they were never present), but
  it is not a substitute for content inspection of everything else.

**Long-running posture — a sharper axis than raw isolation.** E2B and
CubeSandbox are *ephemeral-per-task* by design; a long-running agent is an
architected pattern on top, not the default. E2B: 5-minute default
timeout, continuous runtime tier-capped (~1h Hobby / ~24h Pro), duration
achieved via **pause/resume** (preserves filesystem + memory + processes;
reconnect by sandbox ID via `Sandbox.connect()`; resume resets the timeout
to 5 min; auto-pause via `on_timeout: "pause"`). CubeSandbox mirrors this
(E2B drop-in) with first-class auto pause/resume and hundred-ms
checkpoint/fork — and, self-hosted, sets its own timeout policy with no
vendor tier caps. bot-bottle inverts the model: a bottle is **persistent,
named, and supervised by default** — long-running *is* the default, not a
session-management loop over pause/resume. smolmachines is the other
persistent-by-default project in this set. For anyone building agents that
run for hours/days, this posture difference matters more than the
isolation primitive.

**DX — the "run Claude yolo-style" bar.** The reason `claude
--dangerously-skip-permissions` is so widely used is DX: it's one command
and the agent just goes. The bottle thesis is to make a *sandboxed* run
that easy — `start <agent>` builds the image on first run and drops you
into an interactive Claude session that already has
`--dangerously-skip-permissions` on by default
(`contrib/claude/agent_provider.py`), with the sandbox as the guardrail
instead of per-action prompts. On this axis the field splits cleanly:
- **Wrappers around the agent** (as-easy-as-native): bot-bottle and
  **agent-safehouse** (`safehouse claude --dangerously-skip-permissions`).
  These *are* the run-Claude experience. agent-safehouse is the real DX
  peer — but it's macOS-only Seatbelt, single-run, and doesn't address
  network egress; bot-bottle adds VM-grade isolation, egress DLP, and
  persistent/parallel bottles across macOS + Linux.
- **Libraries / services** (you build the run yourself): boxlite,
  microsandbox, CubeSandbox, E2B. These hand you an SDK or a cluster and
  expect you to wire the agent in — powerful for platform builders,
  heavyweight for "just run Claude on my laptop." microsandbox's MCP/Skills
  angle is *sandbox-as-a-tool the agent calls*, which is the inverse of
  wrapping the agent.
- **In between:** litterbox (wizard + build, Linux only), smolmachines
  (SSH into a named machine), matchlock (run a command in a VM).

So DX is a genuine bot-bottle differentiator, and the only project that
matches it (agent-safehouse) does so with materially weaker isolation and
no egress story. "As easy as native yolo, but actually sandboxed" is a
defensible one-liner.

Why it still doesn't collide head-on:

1. **Shape.** CubeSandbox is a *multi-tenant service for platform
   builders* (drop-in E2B replacement, SDK-driven, 2,000 sandboxes on a
   box). bot-bottle is a *single-operator, declarative-manifest tool for
   the infrastructure I run*. Different buyer, different ergonomics — no
   JSON manifest, no bottle/agent split, no "one command on my laptop."
2. **Backend, not competitor.** Like boxlite/microsandbox, CubeSandbox is
   something bot-bottle could sit *on top of* — a `"runtime": "microvm"`
   or `"runtime": "cubesandbox"` backend under the manifest layer — while
   keeping the manifest, the bottle/agent split, and the local,
   single-operator default.

Why it matters anyway:

- The "nobody else bundles connection-level egress allowlist + audit +
  in-flight credential custody" line is **no longer true for the
  primitive** — a well-funded, 10k-star open-source project now ships it.
  But **content DLP on authorized channels is still not matched** (see
  above), and neither is the *layer above* the primitive (declarative
  manifest, cross-vendor orchestration, operator UX, the
  phone-control/dashboard north star). Those two — outbound-payload DLP
  and the orchestration layer — are where the defensible ground now sits;
  the connection-level allowlist + vault mechanism, on its own, is no
  longer differentiating. Revisit the monetization open/paid line with
  that in mind.
- Worth a closer look at **how** CubeSandbox does credential injection
  and per-sandbox egress tokens (eBPF virtual switch vs. bot-bottle's
  mitmproxy egress proxy) before the next iteration of bot-bottle's
  in-flight-secret feature — see borrowable idea #2 above.