bot-bottle/docs/research/sandbox-agent-sdk-architecture.md

Sandbox Agent SDK and bot-bottle: protocol versus product

This note asks whether Sandbox Agent SDK and bot-bottle compete for the same architectural layer, whether bot-bottle can productize the turnkey ecosystem/DX layer above it, and how far the Docker/OCI analogy actually holds.

Research conducted 2026-07-27. Sandbox Agent SDK was at the 0.4.x line, Apache 2.0, and documented support for Claude Code, Codex, OpenCode, Cursor, Amp, and Pi at the time of review.

Summary

The projects are complementary at the component boundary and competitive at the product boundary. Sandbox Agent SDK normalizes how software controls a coding-agent process inside an arbitrary sandbox. bot-bottle decides what sandbox to create, what trusted role and policy it receives, how credentials and Git access cross the boundary, how traffic is constrained, and how an operator launches and supervises the result.

The Docker analogy is useful with one correction:

• Sandbox Agent SDK is not equivalent to Linux container APIs or OCI itself. It is closer to a containerd shim plus a portable exec/session API for coding agents. It adapts incompatible agent processes to one HTTP/SSE contract.
• A future independent agent-session specification would be the closer OCI analogue.
• bot-bottle can credibly occupy the Docker Engine / Compose / Desktop layer: packaging, policy composition, lifecycle, networking, credentials, storage, operator UX, and a one-command experience above interchangeable agent adapters and isolation runtimes.

That is a viable position, but “turnkey wrapper” undersells it. A thin wrapper is replaceable. The valuable product is a turnkey, policy-first coding-agent runtime whose manifest compiles trusted operator intent into multiple enforcement planes. Sandbox Agent SDK may be one internal process-control component of that product.

The recommended direction is:

1. Keep the bot-bottle manifest as the host-owned source of trusted policy.
2. Spike Sandbox Agent SDK as the in-bottle provider/session adapter.
3. Expose a stable, provider-neutral bot-bottle control API, compatible with Sandbox Agent where practical.
4. Keep security decisions and authoritative audit outside the sandbox.
5. Build the ecosystem around policy packs, agent images, skills, backends, operator UI, and trusted integrations—not around a proprietary transcript protocol.

What each project is today

Sandbox Agent SDK

Sandbox Agent is a Rust server that runs alongside the coding agent. A client connects over HTTP, streams events over SSE, and uses one API across agent implementations. Its documented surface includes:

• creating and restoring agent sessions;
• sending messages and streaming normalized events;
• handling permissions;
• configuring MCP servers, skills, and custom tools;
• filesystem and managed-process APIs;
• interactive terminal access;
• computer-use/desktop operations;
• a universal session/transcript schema;
• an Inspector UI, React components, CLI, TypeScript SDK, and OpenAPI spec.

It can run in embedded mode or inside E2B, Daytona, Modal, Cloudflare Containers, Agent Computer, BoxLite, Docker, and other environments. It explicitly leaves these concerns to the caller or sandbox provider:

• sandbox creation and lifecycle;
• Git repository management;
• durable session storage;
• network policy;
• isolation strength; and
• secure credential delivery.

Its documented credential convenience path extracts real provider credentials from local agent configuration and passes them into the sandbox environment. That is convenient but is not an acceptable security boundary for bot-bottle.

Sources:

• Sandbox Agent repository and architecture
• Sandbox Agent documentation
• HTTP API
• Universal session/transcript schema

bot-bottle

bot-bottle is a host-side launch, policy, and enforcement system for existing coding-agent CLIs. Its current architecture includes:

• agent and bottle manifests with composition via extends:;
• a host-only trust boundary for roles, identity, and secret references;
• provider templates and plugins for Claude Code, Codex, Pi, and custom providers;
• Firecracker on KVM Linux and Apple Container on macOS, with Docker fallback;
• image construction and provider-specific provisioning;
• default-deny inspected egress with path/method/header policy;
• payload DLP on authorized channels;
• real credentials held outside the agent and injected by the gateway;
• Git mediation, upstream credential custody, and gitleaks scanning;
• a per-host authenticated orchestrator and shared gateway;
• named bottle lifecycle, resume, supervision, and audit state; and
• a CLI/TUI intended to make full-permission agents operationally tolerable.

The provider layer currently normalizes launch-time concerns—command, image, prompt delivery, files, skills, environment, verification, and provider-owned egress routes. It does not yet expose a stable provider-neutral runtime contract for sessions, messages, transcripts, terminals, or normalized events. That is the gap Sandbox Agent directly illuminates.

Sources in this repository:

• README.md
• 0070-per-host-orchestrator.md
• 0026-agent-provider-templates.md
• 0053-user-provider-plugins.md
• agent_provider.py

The layer model

The cleanest architecture has four layers:

Layer	Responsibility	Likely owner
Operator product	Install, select a role, launch, observe, intervene, resume, review changes	bot-bottle
Trusted policy and lifecycle	Compose manifest, choose backend/image, hold credentials, enforce egress/Git, persist authoritative audit	bot-bottle
Agent control protocol	Start provider process, create session, send input, stream normalized events, terminal/computer operations	Sandbox Agent or a compatible protocol
Isolation primitive	VM/container/process boundary, filesystem, CPU/memory, networking substrate	Firecracker, Apple Container, Docker, E2B, Daytona, BoxLite, etc.

The important boundary is between trusted policy/lifecycle and agent control. The agent-control daemon runs in the environment being treated as untrusted. It can report what the agent says happened, but it cannot authoritatively prove that policy was enforced. Egress decisions, credential custody, Git scanning, bottle identity, and security audit must remain outside it.

Proposed composition

operator UI / CLI / API
          |
          v
bot-bottle orchestrator  (trusted)
  - resolves manifest
  - owns bottle identity and lifecycle
  - stores authoritative audit
  - authenticates clients
          |
          +--------------------------+
          |                          |
          v                          v
isolation backend              shared gateway  (trusted)
Firecracker / Apple / Docker   - egress policy + DLP
          |                    - credential injection
          |                    - Git mediation
          v
bottle / guest  (untrusted)
  - Sandbox Agent server
  - Claude Code / Codex / Pi subprocess
  - workspace, skills, MCP configuration

The bot-bottle manifest would compile into both sides:

• outside the bottle: backend, network, egress, credentials, Git, supervision, identity, and authoritative lifecycle;
• inside the bottle: selected provider, prompt, skills, MCP configuration, startup arguments, and non-secret session metadata.

Sandbox Agent should never receive real secrets merely because its API offers a credential extraction helper. Provider and forge requests should continue to use bot-bottle's placeholder/proxy pattern.

How accurate is the Docker/OCI analogy?

The useful part

The container ecosystem separates low-level execution from a product that ordinary developers operate. OCI defines interoperable image, runtime, and distribution specifications. Docker Engine adds a daemon, API, CLI, object model, images, networks, volumes, and lifecycle; Docker Desktop and related products add installation, updates, UI, integrations, policy, and team workflows.

The same separation can exist for coding agents:

Container ecosystem	Agent-sandbox ecosystem
OCI/runtime contract	A future open agent session/event contract
runc / runtime adapter	Claude/Codex/Pi adapter
containerd shim and task/exec API	Sandbox Agent server and HTTP/SSE session API
containerd / CRI-style lifecycle	Sandbox-provider lifecycle APIs
Docker Engine / Compose	bot-bottle orchestrator + manifests + backends + gateway
Docker Desktop / Hub ecosystem	bot-bottle desktop/mobile UX, policy packs, agent images, skills, trusted integrations

Sandbox Agent makes coding-agent processes portable in roughly the way a shim makes runtimes consumable through a common lifecycle interface. bot-bottle can make the entire safe-agent system usable without asking the operator to assemble that plumbing.

Official container references:

• Open Container Initiative
• OCI Runtime Specification
• Docker Engine architecture
• Docker alternative runtimes and containerd shims

Where the analogy breaks

1. Sandbox Agent is an implementation, not an independent standard. Its OpenAPI document is public, but the project currently owns the server, adapters, schema, and evolution. OCI is an independently governed set of specifications with multiple implementations.
2. It sits above, not below, the isolation boundary. Linux namespaces, cgroups, VMs, and OCI runtimes create the boundary. Sandbox Agent controls a process after some other system has created that boundary.
3. It reaches into product territory. Inspector, React components, computer-use APIs, skills/MCP configuration, transcripts, and restoration are not merely low-level primitives. Sandbox Agent can continue growing upward into the same UI and orchestration space bot-bottle might occupy.
4. Coding agents are semantically uneven. Normalizing a container lifecycle is easier than claiming full behavioral parity across Claude Code, Codex, Cursor, Amp, OpenCode, and Pi. A universal schema can become a lowest common denominator or accumulate provider-specific escape hatches.
5. The security contract is not standardized. An agent-session API says little about whether credentials are visible, egress is controlled, Git is mediated, or audit is trustworthy. Those are core bot-bottle concerns.

The positioning should therefore say “Docker-like product layer above an open agent-control protocol,” not “Sandbox Agent is OCI” or “bot-bottle implements OCI for agents.”

Can bot-bottle be the turnkey product layer?

Yes, if it owns substantially more than launch syntax.

The turnkey promise is:

Choose a trusted role, point it at a project, and run any supported coding agent with full permissions. bot-bottle builds the environment, isolates it, supplies only the capabilities it needs, keeps credentials outside, mediates external writes, and gives the operator one place to watch and intervene.

That product has several defensible jobs:

1. Packaging and reproducibility

• provider and toolchain images;
• pinned, verified build inputs;
• skills and MCP configuration;
• role/bottle composition;
• cached startup and portable environment definitions; and
• compatibility testing across agents and backends.

2. Trusted policy compilation

The manifest is valuable because one reviewable document compiles into:

• an isolation plan;
• gateway routes and DLP policy;
• credential slots;
• Git-gate repositories and identities;
• provider configuration;
• supervision behavior; and
• operator-facing preflight.

Sandbox Agent's runtime configuration does not replace this. The policy must be resolved before an untrusted guest or agent-control daemon exists.

3. Security enforcement

• dedicated-kernel isolation where available;
• no direct guest route to the internet;
• credentials injected outside the agent;
• content inspection on allowed destinations;
• Git secrets scanning and upstream-key custody;
• fail-closed policy resolution; and
• authoritative host-side audit.

This is the strongest current differentiation from a generic “Sandbox Agent + Docker/E2B” assembly.

4. Lifecycle and operations

• install and host preflight;
• image build/update;
• start, stop, resume, cleanup, and migration;
• concurrent named agents;
• state recovery after crashes;
• live supervision and policy remediation; and
• backend selection without changing the role definition.

5. Ecosystem and DX

A product layer can support:

• curated provider images;
• signed policy/bottle packs;
• reusable role templates;
• skills and MCP bundles;
• backend plugins;
• an authenticated desktop/web/mobile operator client;
• browser/preview integration;
• normalized transcripts and change review; and
• team policy distribution and compliance exports.

The analogy to Docker is strongest here: users adopt the coherent workflow and ecosystem, not because the low-level process API is proprietary.

Business and product positioning

“Turnkey wrapper” is understandable internally but weak externally. It implies that the hard work lives underneath and that another wrapper can replace it. Prefer one of:

• The policy-first runtime for coding agents
• Run any coding agent with full permissions, without giving it your host or credentials
• A turnkey local control plane for isolated coding agents
• Docker-like packaging and operations for coding agents, with the security boundary outside the agent

The open/product split could resemble the container ecosystem:

Open foundation

• manifest schema and composition;
• local CLI and core orchestrator;
• provider adapters;
• Firecracker/Apple Container/Docker backends;
• gateway policy format and enforcement;
• Sandbox Agent compatibility;
• local audit and supervision; and
• conformance tests for providers/backends/policy.

Productizable ecosystem/DX

• polished desktop and mobile clients;
• fleet/remote-host management;
• signed and curated role/image/policy registry;
• team policy distribution and administrative controls;
• durable searchable transcripts and audit exports;
• SSO, RBAC, retention, and tamper-evident audit;
• managed update/compatibility channels;
• remote browser/preview relay;
• enterprise support; and
• optional managed build/cache infrastructure.

OCI itself is not the thing Docker sells. Interoperability expands the market; the product captures value through reliable packaging, workflow, distribution, management, and trust. bot-bottle should follow that logic rather than trying to make its session protocol the moat.

Strategic threat from Sandbox Agent

Sandbox Agent is a real threat for three reasons:

1. It can become the integration default. A frontend or agent platform can integrate one API and choose among many agents and sandbox vendors.
2. It can own session data and UI. The universal event schema, Inspector, React components, restoration, terminal, and computer-use APIs give it a natural path toward the operator surface.
3. Sandbox providers can move upward. If E2B, Daytona, BoxLite, or another runtime combines Sandbox Agent with adequate network policy and credential custody, it can offer much of the turnkey stack.

The threat is not that its manifest syntax is better. It currently has no equivalent trusted policy composition. The threat is that the ecosystem may standardize around its API before bot-bottle has a stable external control surface. In that world bot-bottle is evaluated as one sandbox provider, while the SDK and its consumers own the user relationship.

Why bot-bottle can still win its layer

Sandbox Agent's scope exclusions align with bot-bottle's deepest work:

• it does not choose or operate the sandbox provider;
• it does not mediate Git;
• it does not own network policy;
• it does not securely deliver credentials;
• it does not durably store sessions; and
• it cannot make guest-generated telemetry authoritative.

Those are not incidental features. Together they define the trusted system around an untrusted coding agent. bot-bottle also has a narrower and coherent initial customer: a developer or small operator who wants existing agent CLIs to run locally with broad permissions and bounded consequences.

The durable advantage is therefore:

Sandbox Agent makes agents controllable. bot-bottle makes them safe and operable.

That sentence remains true only if bot-bottle closes its operator-DX gaps. Security without a browser/preview loop, stable API, normalized session view, and good parallel-task UX risks becoming an invisible backend feature.

Integration options

Option A — Embed Sandbox Agent inside each bottle

bot-bottle launches Sandbox Agent as the provider process supervisor and connects it to the host orchestrator through a bottle-scoped authenticated channel.

Benefits

• immediate provider-neutral session API;
• more supported agents;
• normalized streaming and transcripts;
• terminal, filesystem, process, and computer-use primitives;
• Inspector/React ecosystem; and
• less provider-specific reverse engineering in bot-bottle.

Risks

• 0.x API/schema churn;
• extra binary and release-supply-chain dependency;
• lowest-common-denominator normalization;
• conflict with provider-native resume state;
• an in-guest daemon is attacker-controlled after guest compromise;
• duplicate orchestration responsibilities; and
• upstream can move into policy/lifecycle and compete more directly.

Security rule

Treat every event and state claim from Sandbox Agent as untrusted telemetry. Never delegate egress authorization, credential release, bottle identity, authoritative audit, or Git policy to it.

Option B — Implement a Sandbox Agent-compatible endpoint

bot-bottle maps the external protocol onto its existing provider adapters and process model without running the upstream server.

Benefits

• ecosystem compatibility with tighter component control;
• no in-guest daemon dependency; and
• room to preserve bot-bottle-native lifecycle semantics.

Risks

• large and continuing compatibility burden;
• “full feature coverage” is expensive across all providers;
• accidental protocol fork; and
• effort diverted from policy and UX differentiation.

Option C — Define an independent bot-bottle session API

Build only the control surface bot-bottle needs.

Benefits

• clean fit with the trust model and persistent named bottles;
• no upstream dependency; and
• deliberate support for supervision and security events.

Risks

• recreates a fast-growing open-source project;
• no existing client ecosystem;
• slower browser/desktop/mobile work; and
• increases the chance that Sandbox Agent becomes the de facto standard first.

Recommendation

Start with Option A as a bounded compatibility spike, not a product commitment. Do not begin with a clean-room competing protocol.

The spike should answer:

1. Can Claude Code, Codex, and Pi retain exact native resume behavior?
2. Can Sandbox Agent run without receiving real provider credentials?
3. Can its server be reached through a bottle-scoped authenticated channel without exposing the orchestrator or broadening guest egress?
4. Which permission events overlap or conflict with bot-bottle supervision?
5. Can normalized events be stored while clearly separating untrusted transcript telemetry from authoritative gateway/Git audit?
6. Can manifest skills, MCP servers, prompt, and startup arguments compile deterministically into its configuration?
7. Does its versioning policy permit a compatibility contract bot-bottle can support?
8. What image-size, startup-time, and update burden does the binary add?

If the answers are favorable, adopt it behind a bot-bottle-owned interface and pin/test the supported version. If not, implement the smallest compatible subset needed by external clients before inventing a wholly separate API.

Product roadmap implications

The competitor scan and this architecture comparison reorder the likely work:

1. Provider-neutral control/session compatibility spike
2. Stable authenticated external bot-bottle API
3. Normalized transcript/event persistence
4. Parallel-session operator UI
5. Browser/preview/computer-use capability
6. Policy/image/skill distribution and signing
7. Remote host/fleet management

This does not mean pausing security work. It means exposing the shipped security work through a product surface that can compete with the SDK-plus- sandbox ecosystem.

Decision

Treat Sandbox Agent SDK as a potentially standard agent process-control layer, not as a sandbox replacement and not as a minor complementary library. Position bot-bottle one layer above it:

• manifests express trusted role and environment policy;
• bot-bottle compiles and enforces that policy across host, gateway, Git, and isolation backends;
• Sandbox Agent or a compatible protocol controls the selected agent process; and
• bot-bottle owns the turnkey operator experience.

The Docker analogy is strategically sound when stated as:

Sandbox Agent can be the portable task/exec protocol; bot-bottle can be the opinionated engine, Compose-like policy layer, and Desktop-like operator product.

It is not sound when stated as:

Sandbox Agent is OCI and bot-bottle is Docker.

There is no independent OCI-equivalent agent specification yet, and Sandbox Agent already reaches into UI/session territory. Compatibility should be pursued quickly, while the trusted manifest/enforcement plane and operator experience remain the parts bot-bottle deliberately owns.