E2B compatibility matrix

Target: the official E2B SDKs (e2b, @e2b/code-interpreter / e2b_code_interpreter, @e2b/desktop / e2b_desktop) and the e2b CLI work unmodified against vibemon when pointed at it with E2B_DOMAIN / E2B_API_URL / E2B_SANDBOX_URL / E2B_API_KEY.

Sources: spec/e2b/ (vendored upstream specs; provenance in spec/e2b/SOURCES.md). Design: ARCHITECTURE.md.

Legend: Core is what the stripped core (vmm + vmon-agent) provided before the rework. Implementation is what vibemon adds, and where. Proof for each area is in §4a (official SDK suites), §6 (CLI), Distributed, Linux/KVM, and TLS verification and e2e/README.md.

1. What the core VM gives us

2. Control-plane REST API (spec/e2b/infra/spec/openapi.yml)

Every operation is routed. “SDK” = called by the JS/Python SDKs, “CLI” = called by the e2b CLI, “Admin” = operator-only (X-Admin-Token).

Volume-content API (spec/e2b/sdk/spec/openapi-volumecontent.yml): GET|PATCH|DELETE /volumecontent/{id}/path, GET|POST /volumecontent/{id}/dir, GET|PUT /volumecontent/{id}/file — volume JWT auth; object-store volumes are served by the driver directly against S3 (same objects the mounts see), node-local ones are proxied to the owning node. Point the SDK’s E2B_VOLUME_API_URL at the driver when not using https://api.<domain>.

3. envd (spec/e2b/infra/packages/envd/spec/)

Transport: Connect v1 (JSON and proto; unary + enveloped server streams + client stream for StreamInput), HTTP/1.1 + h2c.

4. Infrastructure behaviors

4a. Proven by the official SDK suites

e2e/run.py runs upstream’s unmodified packages/python-sdk/tests and packages/js-sdk/tests (pinned to the spec/e2b/ snapshot) against a monolithic vmon serve. Final macOS/HVF run (2026-10-12): Python 1444 passed / 8 failed / 34 skipped, JS 1006 passed / 2 failed / 36 skipped; skips match upstream CI. Remaining failures: egress header rules (Linux-only feature, 3) and signed download URLs under the macOS Python routing workaround (6). The run’s one JS auto-resume regression was fixed afterwards in the ingress; a JS re-run then gave 1007 passed / 1 failed (egress rules) / 36 skipped. Details and the fixes made are listed in e2e/README.md.

5. Deliberate deviations

• Bring-your-own-bucket mounts (vmonS3Mounts, extension). POST /sandboxes and POST /v2/sandboxes accept vmonS3Mounts: [{path, uri, mode?, endpoint?, region?, credentials?: {accessKeyId, secretAccessKey, sessionToken?}, credentialsSecret?}]: uri is s3://bucket[/prefix] or http(s)://endpoint/bucket[/prefix]; mode is ro (default; lazy read-through), overlay (lazy lower + writes kept on the sandbox disk, gone at kill) or writeback (writes persisted to the bucket on close/fsync); credentialsSecret names a team secret whose value is the credentials JSON (re-read at every resume and fork). Paths must be absolute, clean, and must not overlap each other or volumeMounts; at most 8 S3-backed mounts per sandbox. Without credentials requests are anonymous (never the node’s identity). Endpoints resolving to private/loopback addresses are refused unless the node runs with --s3-mounts-allow-private. Credentials are never logged or returned; the store keeps them only encrypted. Unmodified SDKs cannot send extension fields; use raw HTTP and then Sandbox.connect:

  curl -sX POST "$E2B_API_URL/v2/sandboxes" -H "X-API-Key: $E2B_API_KEY" \
    -H 'Content-Type: application/json' -d '{"templateID": "base",
    "vmonS3Mounts": [{"path": "/mnt/data", "uri": "s3://my-bucket/datasets",
      "mode": "ro", "credentialsSecret": "my-bucket-keys"}]}'
  

  Consistency: last writer wins per object, attributes are cached ≤ 1 s (write-back) / 5 s (ro, overlay), no cross-node locking; directory renames are copy + delete (not atomic, ≤ 10 000 keys, else EXDEV); symlinks and hard links are EPERM.

• GPU sandboxes (extension). Upstream E2B has no GPUs. Here a sandbox gets whole NVIDIA GPUs (or vGPU VFs) passed through when metadata["vmon.gpus"] is a decimal 0–8 (works with stock SDKs: Sandbox.create(metadata={"vmon.gpus": "1"})), else when its template’s environment sets VMON_GPUS (Template().set_envs({"VMON_GPUS": "1"}) or Dockerfile ENV VMON_GPUS=1), else it gets none; metadata wins, so "0" opts a GPU template out. Any other value is 400 naming the key. Placement needs a node with that many free assignable GPUs: sandbox_no_compatible_node when no node has that many at all, sandbox_capacity_unavailable while they are all held. GPU sandboxes always cold-boot, and pauses and snapshots keep the filesystem only: pause() (with or without memory), autoPause, and create_snapshot() stop or capture the disk, and the next resume (manual, connect, or autoResume traffic) boots it again with the GPUs re-reserved, losing guest processes and memory. The requested autoPauseMemory/autoResume flags are validated as upstream and kept as asked. GPU sandboxes are not migrated, so draining a node leaves them running there. The cuda default template (CUDA runtime, one GPU) is a vmon addition. See GPUs.

• Sandbox self-keepalive. X-Access-Token: <envdAccessToken> also authenticates GET /sandboxes/{id}, POST /sandboxes/{id}/timeout, and POST /sandboxes/{id}/refreshes, only for the sandbox that owns that token. The token is compared in constant time before a sandbox lookup; wrong tokens, killed sandboxes, and unknown sandboxes return 401. It grants no access to create, list, kill, pause, connect, snapshots, or any other API route. Existing team blocking and maximum-lifetime rules still apply: timeout and refresh clamp expiry to the owning team’s per-execution maximum, exactly as with API-key authentication. This is a vmon extension, not an upstream E2B capability.

• Admin dashboard. /dashboard/ on the public listener and its GET /admin/cluster, GET /admin/teams, GET /admin/sandboxes endpoints (X-Admin-Token) are vmon extensions with no upstream counterpart.

• Draining a node evacuates it. Upstream’s draining only stops new placements. In vmon the raft leader also migrates the node’s running sandboxes (more than 60 s left) and node-local paused sandboxes to compatible ready nodes (same architecture, backend, CPU baseline; capacity, features, node-local volume pins): pause, transfer of the written disk and dirtied memory, resume. The sandbox ID, guest processes, and memory survive; connections open during the move drop. Sandboxes without a compatible node, and GPU sandboxes, stay. POST /admin/sandboxes/{id}/migrate moves one sandbox on demand (vmon extension).

• Sandbox log fields are strings. SandboxLogEntry.fields is map<string,string>, so non-string envd fields (pid, process_result) reach e2b sandbox logs as strings; upstream’s v1 line keeps their JSON types.

• Init system follows upstream provisioning. Debian/Ubuntu/RHEL/Arch templates boot systemd as PID 1 and Alpine boots busybox init + OpenRC, with vmon-agent installed as the envd service at /usr/bin/envd (upstream package set and init setup, vendored under spec/e2b/infra/packages/orchestrator/pkg/template/build/phases/). Images with an unknown distribution, which upstream rejects, boot the agent as PID 1 instead. When the apt install fails on sources using deb.debian.org or security.debian.org, provisioning switches them to archive.debian.org and retries once, so end-of-life Debian releases still provision; upstream fails the build.

• No Firecracker MMDS. Identity (E2B_SANDBOX_ID, E2B_TEMPLATE_ID, access-token hash) is delivered through /init; there is no 169.254.169.254 service.

• Legacy v1 template builds and the docker.<domain> registry are not served; upstream removed them and current CLIs never call them.

• MCP gateway internals are ours. Upstream’s mcp-gateway image is not public. Ours maps every SDK catalog id except circleci (now an OAuth-only remote server in the Docker catalog; its token/url fields have no counterpart) onto the Docker MCP Catalog v3. Catalog servers needing Docker Desktop OAuth, multi-line secret values, and per-server tool prefixes are not supported; on a tool-name clash the first configured server wins. mcp-gateway --config returns after at most 55 s; servers still starting then (runtime image pulls, long installCmds) appear later with notifications/tools/list_changed. Needs a guest kernel that runs Docker (kernel/); the pinned cloud-hypervisor kernel download cannot.

• Rigs (cluster autoscaling objects) answer 501, the response the spec defines for deployments that do not implement them.

• Bare aliases belong to system teams. Upstream’s v1 publish lets any team claim a bare (non-namespaced) alias. Here only a system team’s public templates hold bare aliases (claimed on v1 or v2 publish), so the SDK defaults (base, code-interpreter-v1, desktop, mcp-gateway) resolve for every team and cannot be squatted; ordinary teams are addressed as <slug>/<alias> (ARCHITECTURE.md §7).

• minFreeDiskMb is validated, not applied. Builds accept it (0 to the team’s max_disk_mb) and record it, but every build disk is already a sparse ext4 image of the team’s max_disk_mb. Free space after the steps is that size minus what they wrote; upstream instead grows the filesystem to the requested free space and keeps it smaller otherwise.

• Default templates are multi-arch. templates/ mirrors the upstream definitions but picks architecture-specific packages at build time (JDK 11: OpenJDK x64 / Temurin aarch64; desktop: Google Chrome on amd64, Chromium as google-chrome-stable on arm64; VS Code repo for the native arch).

• vibemon branding on cosmetic surfaces only: the default guest hostname is vibemon (upstream e2b), the desktop wallpaper and the noVNC page title/icons are vibemon’s. Protocol identifiers (E2B_* env vars, /.e2b, /run/e2b*, e2b/* MIME types, events.e2b.local, user, aliases) are unchanged.

6. e2b CLI (@e2b/cli 2.21.2)

Configuration: E2B_API_URL, E2B_DOMAIN, and (without TLS on the sandbox domain) E2B_SANDBOX_URL. Commands authenticate with E2B_API_KEY or with the project key that e2b auth login stores in ~/.e2b/config.json. The CLI opens the login page at ${E2B_DOCS_BASE:-https://$E2B_DOMAIN/docs}/api/cli. The driver serves that page on any Host that does not address a sandbox, so E2B_DOCS_BASE=http://<api>/docs is only needed when the apex domain does not resolve to the driver over HTTPS. The CLI never reads E2B_ACCESS_TOKEN.

All commands below were proven against a single vmon serve on macOS/HVF, driven by scripts (browser simulator; pexpect for the inquirer prompts and for the PTY).