kvcache-ai/AgentENV

Fork 0

mirror of https://github.com/kvcache-ai/AgentENV.git synced 2026-11-05 01:17:36 +00:00

[GH-ISSUE #211] Add native E2B-compatible persistent volumes #67

New issue

Closed

opened 2026-10-29 14:19:06 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:19:06 +00:00

Owner

Originally created by @yingdi-shan on GitHub (Aug 24, 2026).
Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/211

Problem statement

Add first-class persistent volumes with an E2B-compatible control-plane API and sandbox mounting support.

AgentENV currently supports image-backed attachedDrives, but those drives are coupled to sandbox launch and snapshot state. They do not provide an independent volume identity or lifecycle.

The goal is to support the E2B usage pattern:

const volume = await Volume.create("my-data")

const sandbox = await Sandbox.create({
  volumeMounts: {
    "/mnt/data": volume,
  },
})

This issue supersedes #31. Once native volume mounting is supported, #31 can be closed.

Use case

Mount an immutable dataset into multiple sandboxes.
Create a writable workspace owned by one sandbox.
Preserve the workspace across sandbox pause/resume.
Fork a workspace for child sandboxes without modifying the parent.
Snapshot a volume and restore it as a new writable volume.
Create volumes from existing volumes or OCI/OverlayBD images.
Create and manage volumes from the aenv CLI.

Current behavior and workarounds

attachedDrives is primarily supported on the cold-start path.
Attached drives are image-backed sandbox launch inputs rather than independent resources.
Mount configuration and drive state are coupled to sandbox snapshots.
There are no /volumes CRUD endpoints.
There are no direct volume fork, snapshot, or restore operations.
Shared writable attachment is not supported by the current storage design.

Current workarounds require baking data into templates or using attachedDrives, which prevents the environment and data from evolving independently.

Desired behavior

Implement the E2B-compatible volume endpoints:

POST /volumes
GET /volumes
GET /volumes/{volumeID}
DELETE /volumes/{volumeID}

Responses should include E2B-compatible fields such as volumeID and name. AgentENV-specific metadata may include volume mode, source, lineage, and reservation state.

Support volumeMounts during normal and snapshot-backed sandbox creation:

{
  "volumeMounts": {
    "/mnt/data": "volume-id"
  }
}

Volume modes

`ro`

Immutable content.
Multiple sandboxes may mount the volume concurrently.
Guest writes fail with a read-only filesystem error.
Can be created from an image or an existing volume checkpoint.

`exclusive`

This is the default mode when no mode is specified.

Only one sandbox may own or mount the volume at a time.
A second attachment returns a deterministic conflict, such as 409 Conflict.
A paused sandbox retains its volume reservation.
Another sandbox must fork the volume before using it.
Resume reattaches the original volume to its owner.
Sandbox fork creates an independent copy-on-write child volume.
Sandbox snapshot records a point-in-time volume checkpoint.
Restoring from a checkpoint creates a new exclusive child volume.
Sandbox deletion releases the reservation but does not delete the volume.

`shared-write`

Shared-write volumes are not supported. Explicit requests for this mode must be rejected rather than silently emulated.

Creation sources

Support creating a volume from:

An empty volume.
An existing volume.
An OCI/OverlayBD image.

Creating from an existing volume must not mutate the source:

ro creates an immutable checkpoint.
exclusive creates an independent copy-on-write child.

Direct volume lifecycle operations

Add direct volume-level operations for:

Forking a volume.
Snapshotting a volume.
Restoring/resuming a writable volume from a volume snapshot.

The route names should follow the existing sandbox lifecycle conventions.

CLI

Add, at minimum:

aenv volume create NAME

The command should support:

--mode ro|exclusive
--from-volume VOLUME_ID
--image IMAGE_REFERENCE

Listing, inspecting, deleting, forking, snapshotting, and restoring volumes should use the same aenv volume command group.

Proposed approach

Introduce a first-class volume metadata model independent of sandbox work directories.
Reuse OverlayBD immutable layers and copy-on-write layers for volume snapshots and forks.
Persist volume IDs, source/lineage metadata, and exclusive reservations.
Make reservations durable or scheduler-visible so two nodes cannot acquire the same volume simultaneously.
Thread volume mounts through sandbox creation, fork, snapshot, pause, and resume.
Preserve existing attachedDrives behavior for backward compatibility.
Keep the standalone E2B volume content API outside this issue; volume files are accessed through a mounted sandbox.

Compatibility and operational impact

API/config changes:

Add /volumes endpoints.
Add volumeMounts to sandbox creation and sandbox metadata.
Add volume mode and source fields.
Add direct volume fork, snapshot, and restore operations.
Add aenv volume CLI commands.

Snapshot or storage format changes:

Add persistent volume manifests, lineage, and reservation metadata.
Existing sandbox snapshots and attachedDrives must remain readable.
New snapshots must record volume checkpoints without embedding sandbox-specific paths.

New host/runtime requirements:

No new host permissions should be required beyond the existing OverlayBD/ublk runtime.
Cross-node deployments require durable or scheduler-visible reservation state.
Volume backing storage must be available to the node running the sandbox.

Upgrade and rollback considerations:

Existing attachedDrives clients must continue to work.
Volume metadata should be introduced additively where possible.
Older binaries may not understand newly created volume resources during rolling upgrades.
Deleting a sandbox must not delete an independently managed volume.

Alternatives considered

Extend attachedDrives on POST /sandboxes as proposed in #31.
Support only read-only image-backed volumes.
Support shared-write volumes with ad-hoc locking.
Use host directories or an external shared filesystem.

These alternatives either do not provide an independent lifecycle or exceed the guarantees of the current storage architecture.

Non-goals

Shared-write volumes.
Concurrent writable mounts of one volume.
Standalone E2B volume content operations such as Volume.readFile() and Volume.writeFile().
Arbitrary host-path or network-filesystem volumes.
Per-mount shared-write/read-write coordination.

Pre-submission checklist

I searched existing issues and discussions and did not find a duplicate.
I described a concrete problem and use case, not only a proposed technology.
I understand that acceptance of the problem does not imply approval of a particular implementation.

Originally created by @yingdi-shan on GitHub (Aug 24, 2026). Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/211 ## Problem statement Add first-class persistent volumes with an E2B-compatible control-plane API and sandbox mounting support. AgentENV currently supports image-backed `attachedDrives`, but those drives are coupled to sandbox launch and snapshot state. They do not provide an independent volume identity or lifecycle. The goal is to support the E2B usage pattern: ```ts const volume = await Volume.create("my-data") const sandbox = await Sandbox.create({ volumeMounts: { "/mnt/data": volume, }, }) ``` This issue supersedes [#31](https://github.com/kvcache-ai/AgentENV/issues/31). Once native volume mounting is supported, #31 can be closed. ## Use case - Mount an immutable dataset into multiple sandboxes. - Create a writable workspace owned by one sandbox. - Preserve the workspace across sandbox pause/resume. - Fork a workspace for child sandboxes without modifying the parent. - Snapshot a volume and restore it as a new writable volume. - Create volumes from existing volumes or OCI/OverlayBD images. - Create and manage volumes from the `aenv` CLI. ## Current behavior and workarounds - `attachedDrives` is primarily supported on the cold-start path. - Attached drives are image-backed sandbox launch inputs rather than independent resources. - Mount configuration and drive state are coupled to sandbox snapshots. - There are no `/volumes` CRUD endpoints. - There are no direct volume fork, snapshot, or restore operations. - Shared writable attachment is not supported by the current storage design. Current workarounds require baking data into templates or using `attachedDrives`, which prevents the environment and data from evolving independently. ## Desired behavior Implement the E2B-compatible volume endpoints: - `POST /volumes` - `GET /volumes` - `GET /volumes/{volumeID}` - `DELETE /volumes/{volumeID}` Responses should include E2B-compatible fields such as `volumeID` and `name`. AgentENV-specific metadata may include volume mode, source, lineage, and reservation state. Support `volumeMounts` during normal and snapshot-backed sandbox creation: ```json { "volumeMounts": { "/mnt/data": "volume-id" } } ``` ### Volume modes #### `ro` - Immutable content. - Multiple sandboxes may mount the volume concurrently. - Guest writes fail with a read-only filesystem error. - Can be created from an image or an existing volume checkpoint. #### `exclusive` This is the default mode when no mode is specified. - Only one sandbox may own or mount the volume at a time. - A second attachment returns a deterministic conflict, such as `409 Conflict`. - A paused sandbox retains its volume reservation. - Another sandbox must fork the volume before using it. - Resume reattaches the original volume to its owner. - Sandbox fork creates an independent copy-on-write child volume. - Sandbox snapshot records a point-in-time volume checkpoint. - Restoring from a checkpoint creates a new exclusive child volume. - Sandbox deletion releases the reservation but does not delete the volume. #### `shared-write` Shared-write volumes are not supported. Explicit requests for this mode must be rejected rather than silently emulated. ### Creation sources Support creating a volume from: - An empty volume. - An existing volume. - An OCI/OverlayBD image. Creating from an existing volume must not mutate the source: - `ro` creates an immutable checkpoint. - `exclusive` creates an independent copy-on-write child. ### Direct volume lifecycle operations Add direct volume-level operations for: - Forking a volume. - Snapshotting a volume. - Restoring/resuming a writable volume from a volume snapshot. The route names should follow the existing sandbox lifecycle conventions. ### CLI Add, at minimum: ```text aenv volume create NAME ``` The command should support: - `--mode ro|exclusive` - `--from-volume VOLUME_ID` - `--image IMAGE_REFERENCE` Listing, inspecting, deleting, forking, snapshotting, and restoring volumes should use the same `aenv volume` command group. ## Proposed approach - Introduce a first-class volume metadata model independent of sandbox work directories. - Reuse OverlayBD immutable layers and copy-on-write layers for volume snapshots and forks. - Persist volume IDs, source/lineage metadata, and exclusive reservations. - Make reservations durable or scheduler-visible so two nodes cannot acquire the same volume simultaneously. - Thread volume mounts through sandbox creation, fork, snapshot, pause, and resume. - Preserve existing `attachedDrives` behavior for backward compatibility. - Keep the standalone E2B volume content API outside this issue; volume files are accessed through a mounted sandbox. ## Compatibility and operational impact **API/config changes:** - Add `/volumes` endpoints. - Add `volumeMounts` to sandbox creation and sandbox metadata. - Add volume mode and source fields. - Add direct volume fork, snapshot, and restore operations. - Add `aenv volume` CLI commands. **Snapshot or storage format changes:** - Add persistent volume manifests, lineage, and reservation metadata. - Existing sandbox snapshots and `attachedDrives` must remain readable. - New snapshots must record volume checkpoints without embedding sandbox-specific paths. **New host/runtime requirements:** - No new host permissions should be required beyond the existing OverlayBD/ublk runtime. - Cross-node deployments require durable or scheduler-visible reservation state. - Volume backing storage must be available to the node running the sandbox. **Upgrade and rollback considerations:** - Existing `attachedDrives` clients must continue to work. - Volume metadata should be introduced additively where possible. - Older binaries may not understand newly created volume resources during rolling upgrades. - Deleting a sandbox must not delete an independently managed volume. ## Alternatives considered - Extend `attachedDrives` on `POST /sandboxes` as proposed in #31. - Support only read-only image-backed volumes. - Support shared-write volumes with ad-hoc locking. - Use host directories or an external shared filesystem. These alternatives either do not provide an independent lifecycle or exceed the guarantees of the current storage architecture. ## Non-goals - Shared-write volumes. - Concurrent writable mounts of one volume. - Standalone E2B volume content operations such as `Volume.readFile()` and `Volume.writeFile()`. - Arbitrary host-path or network-filesystem volumes. - Per-mount shared-write/read-write coordination. ## Pre-submission checklist - [x] I searched existing issues and discussions and did not find a duplicate. - [x] I described a concrete problem and use case, not only a proposed technology. - [x] I understand that acceptance of the problem does not imply approval of a particular implementation.

bsakaguchi

2026-10-29 14:19:06 +00:00