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 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.