bot-bottle/docs/research/landscape-containerized-claude.md

# Landscape: containerized AI coding agent tools

Research into whether bot-bottle is redundant with existing projects, and
whether it's worth publishing.

## Summary

The "AI coding agents in isolated sandboxes" space is active but not saturated.
bot-bottle occupies a distinct position: no surveyed project combines all five
of its defining features. Publishing is likely worthwhile, with the main risk
being claudebox expanding to absorb the same niche.

**Updated 2026-07-09:** bot-bottle now supports three isolation backends
(Docker, Apple `container`, smolmachines/libkrun microVMs) and three built-in
agent providers (Claude Code, OpenAI Codex, Pi) with an open plugin system for
arbitrary providers. This meaningfully strengthens the differentiation against
all surveyed competitors.

## Closest competitor: claudebox

[RchGrav/claudebox](https://github.com/RchGrav/claudebox) is the most
feature-complete analog. It runs Claude Code in Docker with per-project
isolated images, 15+ pre-configured dev-language profiles, and per-project
network firewall allowlists. Actively maintained with multiple forks.

What it lacks: manifest-driven named agents, per-agent env resolution modes
(prompt / host-forward / literal), skill directory injection, per-agent system
prompts, SSH-agent forwarding without copying private keys, home+project
manifest merge.

## Other surveyed projects

- **textcortex/claude-code-sandbox → spritz** — evolved toward
  Kubernetes-native multi-agent infra; not stdlib-first or local-Docker.
  Original sandbox repo is archived.
- **trailofbits/claude-code-devcontainer** — devcontainer config for security
  audits; not a general agent launcher.
- **Several small solo repos** (arezi/claude-sandbox, nkrefman/claude-sandbox,
  VishalJ99/claude-docker) — lightweight Docker wrappers with no multi-agent
  config layer.
- **Docker's official sandbox templates** — launch-and-run Dockerfiles plus an
  npm-based runtime; not a manifest-driven fleet manager.

## Adjacent (different model)

- **dagger/container-use** (mid-2025) — exposes an MCP server so the *agent*
  spins up its own containers with Git worktrees. Inverted model vs. bot-bottle
  (agent controls container rather than being launched into one by a manifest).
  Still marked early-development.
- **E2B, Northflank, Cloudflare Sandbox SDK** — cloud-hosted SaaS sandbox
  runtimes; fundamentally different architecture.
- **superhq.ai / SuperHQ** (v0.4.4, April 2026) — macOS desktop app (Rust/GPUI)
  that runs Claude Code, Codex, and Pi inside microVMs via Apple's
  Virtualization.framework (their own shuru-sdk / libkrun). Auth gateway
  injects API keys on the wire so the sandbox never sees them; tmpfs overlay
  stages agent writes for diff-and-accept review; mobile remote access via
  remote.superhq.ai. Early alpha, free on launch, Apple Silicon only.

  Overlap: both projects cover agent isolation, credential proxying, and
  multi-provider support (Claude Code / Codex / Pi). Differences: SuperHQ is a
  GUI desktop app with no manifest layer; bot-bottle is a CLI fleet manager with
  named agents, skills injection, per-agent system prompts, and cross-platform
  backends (Docker, Apple `container`, smolmachines). SuperHQ's microVM
  isolation story is now partially matched by bot-bottle's `macos_container` and
  smolmachines backends. Worth watching — it targets the same security-minded
  power-user audience and moves fast.

  **Known gap in SuperHQ (user-requested, as of 2026-07-09):** A named user
  (Brian Cheong, Founder, Dunialabs.io) explicitly called out the absence of
  per-run audit logging: tool calls and network egress. Bot-bottle covers both:
  network egress is logged by pipelock/mitmproxy, and per-run op-log/audit state
  is persisted to SQLite.

## What no found project does

None combine:
1. Named-agent manifest with per-agent env resolution (prompt / host-forward / literal), supporting multiple providers (Claude Code, Codex, Pi, arbitrary plugins)
2. Skills directory injection
3. Per-agent system prompts
4. SSH-agent key forwarding without copying private keys into the container
5. Home + project manifest merge
6. Pluggable isolation backends: Docker (Linux/macOS), Apple `container` (macOS microVMs), smolmachines/libkrun microVMs
7. Per-run audit log: network egress via pipelock/mitmproxy + op-log persisted to SQLite

**In-flight directions (not yet shipped):**

- **Forge-native dispatch (issue #317):** Gitea webhook → orchestrator spins up a bottle
  with the issue body as prompt → agent works → bottle freezes awaiting review comment →
  rehydrates on comment → tears down on PR close. The issue-to-PR lifecycle concept is not
  novel (Devin, Copilot Workspace, SWE-agent all do this as cloud services); what's
  distinct is doing it self-hosted, manifest-driven, inside bot-bottle's isolation
  primitives.
- **Paid web control plane (issue #327):** Browser-based multi-host agent launch and
  monitoring; account-scoped bottle and agent definitions; secret custody (encrypted at
  rest, injected into the sidecar at launch, never exposed to the agent or returned by any
  read API). Monetization model: OSS runtime free, control plane paid — a standard split
  (HashiCorp, Grafana) applied to a self-hosted agent sandbox. The principled secret
  custody model (agent never sees real credentials, even via printenv) is more rigorous
  than most surveyed tools but not unprecedented.

## Publishing verdict

Worth publishing. Differentiators that matter to the target audience (power
users running parallel AI coding agent sessions with distinct personas/tooling):

- The Python-stdlib-first, low-dependency design — competitors are npm-based,
  Rust/GUI, or Kubernetes-native.
- Named agents with distinct skills and system prompts, not just language profiles.
- Multi-backend isolation: Docker, Apple `container` microVMs, and
  smolmachines/libkrun — single manifest works across all three.
- Multi-provider: Claude Code, Codex, Pi, plus an open plugin system for
  arbitrary providers.
- SSH forwarding without key copying.
- Per-run audit log (tool calls + network egress) — an explicitly requested gap
  in SuperHQ as of 2026-07-09.
- Forge-native dispatch and a paid control plane (in flight) bring bot-bottle
  into the same product category as cloud services like Devin and Copilot
  Workspace — but self-hosted, with stronger isolation guarantees and a
  manifest-driven fleet model those services don't have.

Main risk: claudebox adds manifest/agent config; SuperHQ is moving fast on the
GUI / microVM side. The space is moving fast enough that publishing sooner is
better if establishing prior art matters.

Discovery will be slow without active promotion; an Anthropic Discord post or
HN "Show HN" would do most of the work.

## Caveats

- GitHub search cannot surface private or very new repos comprehensively.
- Counts (stars, forks) were not confirmed for every project.
- Initial research conducted 2026-05-07; SuperHQ entry added 2026-07-09; the space moves fast.