Official E2B 2.64.0 Volume API, Durable Store, and Sandbox Mounts
此内容尚不支持你的语言。
Source:
docs/enhancements/0025-e2b-volumes/README.md· Status:implemented· Area:storage· Milestone:v0.4| Stage | Status | Created | Updated | Owning Area | | :--- | :--- | :--- | :--- | :--- | |alpha|implemented|2026-11-15|2026-11-15|storage(gateway,runtime,controller) |
Table of Contents
Section titled “Table of Contents”- Release Signoff Checklist
- Summary
- Motivation
- Proposal
- Design Details
- Production Readiness Review Questionnaire (PRR)
- Implementation History
- Drawbacks
- Alternatives
Release Signoff Checklist
Section titled “Release Signoff Checklist”- Enhancement design documented in
docs/enhancements/0025-e2b-volumes/ - Official E2B 2.64.0 Volume management and
/volumecontentREST routes implemented - Symlink-safe fd-based content API (
openat2/O_NOFOLLOWdirfd walk +fchown/fchmod) verified - On-disk UID/GID (
1000:1000) and mode (& 0o777) invariants enforced;nosuid,nodevon Docker bind volumes - Live Kubernetes runtime gated off (
501 Not Implemented) in Alpha until shared CSI/Kata storage is implemented - Unit and regression tests passing (
go test -race ./pkg/volume/... ./pkg/gateway/... ./pkg/controller/... ./pkg/runtime/...)
Summary
Section titled “Summary”CEP-0025 adds support for the official E2B 2.64.0 Volume API (POST/GET /volumes, GET/DELETE /volumes/{volumeID}), the authenticated Volume Content API (/volumecontent/{volumeID}/file|dir|path), and sandbox creation volumeMounts attachment in cubepod-gateway and pkg/runtime. Volumes are stored in a durable gateway-local directory (pkg/volume) isolated per API-key tenant and mounted into Docker sandboxes at creation time.
In Alpha, volumeMounts is active on the Local Development (Docker) runtime and explicitly gated off (501 Not Implemented) on live Kubernetes (Kata + CSI) until a shared-storage backend bridges the gateway content API and Kata microVM pods across pivot_root. See CEP-0026 for the follow-up Kubernetes/Kata integration design.
Motivation
Section titled “Motivation”Official E2B 2.64.0 SDKs (Volume.create, Volume.write_file, Sandbox.create(volume_mounts=...)) allow agents and orchestrators to pre-populate reusable datasets out-of-band and mount them into sandboxes at arbitrary paths (distinct from CubePod’s /workspace VolumeKey). Without these endpoints, E2B SDK volume workflows fail against cubepod-gateway.
- Implement E2B 2.64.0 Volume management (
/volumes) and content (/volumecontent/{volumeID}/...) HTTP APIs. - Isolate volume data per tenant (
sha256(X-API-KEY)), protect against symlink TOCTOU host-root escapes, and enforce AGENTS.md Invariant 4 (1000:1000cubeplexownership, no setuid/uid=0 on disk). - Attach mounted volumes to Docker sandboxes (
HostConfig.Bindsornosuid,nodevnamed Docker bind volumes) while keeping/workspaceand/rootfs-upperstrictly independent (Invariant 1). - Record
PodBoxSpec.E2BVolumeMountsand controller manifest plumbing (e2bvol-<id>) for future Kubernetes support, while gating off live KubernetesvolumeMountsin Alpha.
Non-Goals
Section titled “Non-Goals”- Live Kubernetes Kata + CSI shared volume content: Backing
/volumecontentwith a cluster-wide RWX/CSI-attached PVC and carrying mounts acrosspodd-initpivot_rootis deferred to Beta. - External KMS / API-key rotation migration: Tenant identity is derived from
sha256(X-API-KEY)in Alpha; rotating a key orphans that key’s volumes. - Refactored per-sandbox gateway locking: Eliminating
Server.muacross slowstartRuntimeSandbox/pauseRuntimeSandboxcalls inpkg/gateway/sandboxes.gois deferred to a dedicated gateway concurrency cleanup.
Proposal
Section titled “Proposal”User Stories
Section titled “User Stories”- As an E2B SDK user (local Docker runtime), I can create a named volume, upload files via
Volume.write_file, launch a sandbox withvolumeMounts: [{name, path}], and read/write those files inside the sandbox while keeping/workspaceseparate. - As a cluster operator, I get a clear
501 Not Implementederror if a client requestsvolumeMountson a live Kubernetes (Kata + CSI) deployment in Alpha, rather than silent data divergence between the gateway and the pod.
Notes / Constraints / Caveats
Section titled “Notes / Constraints / Caveats”- Dual-Runtime Behavior:
- Local Development (
Docker + Loopback ext4): Supported in Alpha. Volume bytes live under<stateDir>/e2b-volumes/<id>/data(0700parent,1000:1000data/). WhenCUBEPOD_E2B_DOCKER_VOLUMES=1,pkg/volumeprovisions a named Dockerlocalbind volume (o: "bind,nosuid,nodev") verified on 409 conflict. - Production Kubernetes (
Kata + CSI Block): Gated off in Alpha. WhenlivePodRouting && runtime == nil,POST /sandboxeswith non-emptyvolumeMountsreturns501 Not Implemented, andensureE2BVolumePVCskips creatinge2bvol-<id>PVCs. Controller manifest helpers (applyOfficialVolumeMounts,ValidateOfficialVolumeMounts) and CRD schema (PodBoxSpec.E2BVolumeMounts) are present and unit-tested withMemoryKubeClient, but unreachable on live K8s until Beta.
- Local Development (
- Test-only Docker Flags:
CUBEPOD_DOCKER_INJECT_BIN=0andCUBEPOD_DOCKER_BIND_STORAGE=0incmd/cubepod-gateway/main.goare test-only overrides for local compose harnesses; they emit a warning log and must never be disabled in production (AGENTS.md Invariants 1 & 2).
Risks and Mitigations
Section titled “Risks and Mitigations”| Risk | Impact | Mitigation |
|---|---|---|
Symlink TOCTOU race by sandbox code modifying data/ while gateway runs as root |
Host-root file overwrite, chmod/chown escape |
All pkg/volume content ops use openDataRoot (O_DIRECTORY|O_NOFOLLOW), openat2(RESOLVE_BENEATH|RESOLVE_NO_SYMLINKS) with O_NOFOLLOW dirfd walk fallback, fstatat(AT_SYMLINK_NOFOLLOW), and fchown/fchmod on open fds. |
API uid=0 or mode=04755 planting setuid-root binaries |
Privilege escalation inside sandbox | On-disk ownership is always 1000:1000 (defaultDataUID:defaultDataGID); mode is masked to 0o777 on disk and in attrs.json. Requested uid/gid are stored as metadata only. Docker bind volumes mount nosuid,nodev. |
| Slow upload or Docker call blocking all tenants | Gateway DoS | WriteFile streams to a private 0700 temp file outside data/ with no lock held, then commits under per-volume rec.mu. Store.mu is released around Docker Engine HTTP calls. http.MaxBytesReader caps uploads (default 64 MiB -> 413). |
| Unbounded volume creation per API key | Disk exhaustion | MaxVolumesPerTenant (default 64) returns ErrLimitExceeded (429 Too Many Requests). |
Stale mounts.json after gateway crash |
Delete blocked forever with 409 Conflict |
Store.ReconcileMounts prunes unknown sandbox IDs on ConfigureE2BVolumes startup. |
Volume mounted over /rootfs-upper or reserved paths |
Violates Invariant 1 / breaks container | reservedE2BMounts includes /rootfs-upper, /workspace, /opt/cubepod, /mnt/cubepod, /proc, /sys, /dev, /etc, /bin, /sbin, /usr, /lib, /lib64, /root, /boot, /run. Path-segment validation rejects .. while permitting filenames like /mnt/a..b. |
Design Details
Section titled “Design Details”API / CRD / Wire Changes
Section titled “API / CRD / Wire Changes”- Management API (
X-API-KEY):POST /volumes(201): creates volume, returns{volumeID, name, token}.GET /volumes(200): lists tenant volumes (tokens omitted).GET /volumes/{volumeID}(200): returns{volumeID, name, token}.DELETE /volumes/{volumeID}(204,409if mounted).
- Content API (
Authorization: Bearer <token>, constant-time compare):GET /volumecontent/{volumeID}/file?path=...PUT /volumecontent/{volumeID}/file?path=...&uid=...&gid=...&mode=...&force=...(http.MaxBytesReader,413on overflow)GET /volumecontent/{volumeID}/dir?path=...&depth=...POST /volumecontent/{volumeID}/dir?path=...&uid=...&gid=...&mode=...&force=...GET /volumecontent/{volumeID}/path?path=...PATCH /volumecontent/{volumeID}/path?path=...(JSON{uid, gid, mode})DELETE /volumecontent/{volumeID}/path?path=...
- Sandbox Create (
api/openapi/cubepod-v1.yaml):volumeMounts: [{name, path}]. - CRD (
api/v1alpha1/types.go,deploy/helm/cubepod/crds/cubepod.io_podboxes.yaml):PodBoxSpec.E2BVolumeMounts(maxItems: 32,volumeID^[a-f0-9]{32}$,pvcName^e2bvol-[a-f0-9]{32}$,path^/.+).
State Machine & Data Flow
Section titled “State Machine & Data Flow”flowchart LR
Client["E2B SDK Client"] -->|"X-API-KEY / Bearer token"| GW["cubepod-gateway (pkg/gateway/volumes.go)"]
GW -->|"stage temp file (no lock)"| VolDir["<dir>/<id>/.upload-* (0700)"]
VolDir -->|"rec.mu + openat2/dirfd + renameat"| DataDir["<dir>/<id>/data (1000:1000)"]
GW -->|"Docker runtime"| Docker["DockerBackend (Binds or bind,nosuid,nodev volume)"]
GW -.->|"Live K8s (Alpha gated)"| Gated["501 Not Implemented"]Security & Concurrency Model
Section titled “Security & Concurrency Model”- Tenant Trust Model: Any non-empty
X-API-KEYhashes totenant = sha256("cubepod-e2b-volume-v1\x00" + apiKey). Rotating an API key changes the tenant hash and orphans prior volumes. Gateway deployments rely on upstream ingress/auth or trusted callers; per-tenant volume count is capped (MaxVolumesPerTenant, default 64). Note:/sandboxesroutes themselves do not enforce per-tenant ownership in Alpha, so tenant isolation applies to/volumes,/volumecontent, andvolumeMountslookup/commit. - Locking:
Store.muprotects in-memory maps (vols,byName,mounts) and is never held acrossio.Copyor Docker Engine HTTP calls. EachvolRechas its ownmu sync.Mutexfor filesystem commit andattrs.jsonpersistence. Known limitation:Server.muinpkg/gateway/sandboxes.gois still held acrossstartRuntimeSandbox/pauseRuntimeSandbox(deferred).
Boundary Conditions & Failure Recovery
Section titled “Boundary Conditions & Failure Recovery”- Gateway crash:
meta.json,attrs.json, andmounts.jsonare written atomically (0600temp file +fsync+rename). On restart,ReconcileMountsclears stale sandbox mount records. - K8s future design (Beta): To enable
volumeMountson Kubernetes Kata + CSI, the gateway content API must read/write the same shared storage (e.g., RWX PVC orpoddproxy) rather than gateway-local disk,podd-initmust preserve non-/workspacemount points acrosspivot_root, and forked sandboxes must clone or share read-only rather than sharing an RWO PVC.
Test Plan
Section titled “Test Plan”- Unit & Concurrency Tests (
pkg/volume/store_test.go):- Symlink escape rejection across
WriteFile,OpenFile,Patch,MakeDir,ListDir,Stat,Remove. - Concurrent symlink-swap race test (
TestStore_ConcurrentSymlinkSwapRace). - Setuid/uid=0 stripping on disk + metadata preservation (
TestStore_StripsSetuidAndPreservesMetadata). - Per-tenant quota,
/mnt/a..bvs/../escape,ReconcileMounts, andensureBindVolumebind,nosuid,nodev+ 409 device verification.
- Symlink escape rejection across
- Gateway & Controller/Runtime Tests (
pkg/gateway/volumes_test.go,pkg/controller/manifests_test.go,pkg/runtime/runtime_test.go):- Live K8s
501gating and no PVC creation (TestE2BVolumeLiveK8sGatedOff). 413upload size limit and429tenant cap.ValidateOfficialVolumeMountserror propagation (no silent drop) and/rootfs-upperrejection.- Docker
BuildRunArgs--cpus(NanoCPUs) andEngineAPIvolume mount.
- Live K8s
Graduation Criteria
Section titled “Graduation Criteria”- Alpha (Current): Local Docker runtime supported; symlink-safe fd I/O, upload caps, tenant quota, and
nosuid,nodevverified; live K8s gated off with501. - Beta: Shared CSI/Kata volume content backend,
podd-initpivot_rootmount preservation, per-sandboxServer.mudecoupling, and live K8s E2E tests. - GA: Production bake time in CubePlex with API-key rotation/tenant auth integration.
Upgrade / Downgrade Strategy
Section titled “Upgrade / Downgrade Strategy”PodBoxSpec.E2BVolumeMountsis an optional field (omitempty); existingPodBoxCRs,/workspacePVCs, and/rootfs-upperPVCs are unaffected.
Production Readiness Review Questionnaire (PRR)
Section titled “Production Readiness Review Questionnaire (PRR)”- Feature Enablement and Rollback: Enabled via
CUBEPOD_E2B_VOLUME_DIR(orstateDir/e2b-volumes). Removing the dir config disables routes without affecting/workspace. - Rollout, Upgrade and Rollback Planning: Atomic JSON metadata survives gateway restarts;
ReconcileMountscleans stale mounts on startup. - Monitoring Requirements: Structured
slogwarnings on test-only Docker flags and mount copy/delete errors; HTTP413/429/501status codes. - Dependencies: Linux
openat2(withO_NOFOLLOWdirfd walk fallback for older kernels) and Docker Engine API for named bind volumes. - Scalability: Per-volume locking and off-lock
WriteFilestaging prevent one slow upload from blocking other volumes;MaxVolumesPerTenantbounds disk usage. - Troubleshooting: Inspect
<e2b-volumes>/<id>/meta.jsonandmounts.json; restart gateway to reconcile stale mounts.
Implementation History
Section titled “Implementation History”- 2026-11-15: Implemented E2B 2.64.0 Volume store, gateway REST API, Docker runtime mounts, CRD/controller plumbing, security hardening (symlink-safe fd I/O,
1000:1000+0o777masking, per-volume locks, upload/tenant caps, K8s Alpha gating), and CEP-0025.
Drawbacks
Section titled “Drawbacks”- Maintaining a gateway-local volume store in Alpha limits
volumeMountsto single-gateway Docker deployments until Beta shared-storage support lands.
Alternatives
Section titled “Alternatives”- Direct
os.Lstat+ path-basedos.Open/os.Chown: Rejected due to TOCTOU symlink-swap races when sandboxes sharedata/read-write. - Exposing live K8s
e2bvol-<id>PVCs in Alpha: Rejected because gateway-localdata/and Kata pod PVCs would hold diverging copies of data andpodd-initpivot_rootdrops non-/workspacemounts.