E2B architecture: SDKs, templates, and Firecracker

SDK objects and runtime interfaces

From the caller's perspective, E2B has a focused model: templates define reusable environments, sandboxes represent time-bounded isolated instances, and commands, files, and PTY provide execution interfaces. A model should not own these capabilities directly; an agent should reach the SDK through governed tools.

A GoClaw E2B adapter must not leak SDK objects into the public API. The stable contract should retain provider, environment, sandbox, operation, artifact, and usage concepts while placing E2B-specific fields behind capability evidence or provider extensions.

• The control plane owns authentication, authorization, approval, budget, idempotency, and audit.
• The provider adapter owns protocol details, retries, error mapping, and capability differences.
• The sandbox data plane receives only approved and constrained execution requests.

Template builds and snapshots

The official build flow creates a container filesystem, performs installation and configuration, starts a sandbox, waits for readiness when a start command exists, and then snapshots the running filesystem and processes.

This explains both fast restoration with an already-running service and a common trap: environment variables passed to Sandbox.create cannot affect a start command that already ran during the build. Variables required by that process belong in the template definition.

Lifecycle and error mapping

Create, connect, execute, pause/resume, timeout, and terminate must map into one stable state machine. A client finally block provides fast release, a platform TTL reclaimer provides compensation, and the control plane must handle unknown outcomes such as provider success followed by a lost response.

Metadata should correlate workspace, invocation, and run without containing secrets. Error mapping must distinguish authentication failure, rate limits, capacity exhaustion, timeout, non-zero command exit, and provider unavailability.

import { Sandbox } from "e2b";

const sandbox = await Sandbox.create("coding-agent:stable", {
  timeoutMs: 5 * 60 * 1000,
  metadata: { workspace: "ws_42", invocation: "inv_1042" },
});

try {
  const result = await sandbox.commands.run(
    "git --version && python --version"
  );
  console.log(result.exitCode, result.stdout);
} finally {
  await sandbox.kill();
}

What the Firecracker data plane covers

E2B runs sandboxes in Firecracker microVMs. A microVM gives a clearer kernel boundary than a shared container, but a platform still needs image and snapshot storage, template building, routing, scheduling, logs, metrics, identity, and lifecycle management.

Using Firecracker does not mean a team has reproduced E2B. The difficult work is composing these pieces into an operable system under concurrency, recovery, version evolution, and multi-tenant constraints.

• Isolation: guest kernel and host boundary.
• Supply: template builds, snapshots, kernels, and Firecracker versions.
• Scheduling: capacity, node selection, concurrency, and reclamation.
• Governance: network, secrets, audit, budget, and tenant boundaries.

Deployment boundaries for BYOC and self-hosting

E2B BYOC currently targets AWS and GCP. Templates, snapshots, and runtime logs stay in the customer VPC, and sensitive sandbox traffic flows directly there; E2B Cloud still participates in platform, observability, and cluster management.

The open-source self-host path requires a fuller Terraform stack. The official AWS reference uses Nomad/Consul node pools, object storage, container registries, databases, and Firecracker orchestrator nodes with nested virtualization.

Mapping E2B into GoClaw

GoClaw maps templates to versioned environments and sandboxes to short-lived instances. Provider capabilities carry versions and verification evidence; run results retain logs, exit status, artifacts, traces, usage, and audit.

E2B, ACS, local, and a future owned data plane implement the same GoClaw runtime contract, while provider-specific constraints remain in capability declarations and extension fields.

• Unify the control plane; keep the data plane replaceable.
• Validate capability claims through conformance tests.
• Put unknown outcomes, cancellation races, and TTL cleanup into E2E scenarios.
• Expose differences instead of hiding them behind a lowest common denominator.

Primary sources and further reading

Technical details in this article come from the official documentation and repositories below. Check the documentation for your version before implementation.