[Primary33]

What

Reject explicit volumeMounts, including [], when launching a sandbox snapshot that contains volumes.

Why

The restored guest retains its captured filesystems. Rebinding those drive slots to different volumes can corrupt data. Following the maintainer discussion, reject replacement instead of implementing the staging and unmount machinery in #404.

Related issue

Supersedes #404. Prerequisite for #398.

Scope and non-goals

Warm-start validation, API descriptions, CLI documentation, and regression coverage.

Design and behavior changes

Check the original optional field before allocating or reserving volumes. Omitting it restores the captured snapshot volumes. Templates still accept explicit mounts, as do snapshots without volumes. Both creation endpoints share this check.

Compatibility and operations

• API: previously accepted replacement requests now return HTTP 400. E2B JS SDK 2.58.0 omits the field by default; explicit empty mounts serialize as [].
• Configuration, snapshot format, and host requirements: unchanged.

Validation

Tested on Ubuntu 24.04 as a non-root user with isolated state, dependencies, ports, and network ranges.

• make agentenv-server with OpenAPI Generator 7.22.0
• make fmt
• make clippy
• cargo test -p agentenv --lib snapshot_volume_replacement
• make test-unit — 1206 passed, plus shell checks; CLI tests serialized
• 15_volume.sh — 56 assertions, including both endpoints and empty arrays
• 16_volume_randomized.sh — 1696 assertions; Compose, seed 21106, 50 steps
• E2B TypeScript SDK 2.58.0 volume compatibility and mount serialization checks
• Documentation updated

Risks and reviewer notes

Empty arrays intentionally count as explicit replacement requests.

Checklist

• One coherent change with regression coverage.
• Schema and generated models updated together.
• Examples and logs contain no credentials.

[Copilot]

🟢 Approval recommended

The narrowly scoped validation preserves implicit restoration, has regression coverage, and leaves no unresolved findings.

No open issues 🎉

What changed in this PR

Prevents unsafe volume replacement when launching AgentENV templates or snapshots with captured volumes.

Changes:

• Rejects explicit volumeMounts, including [], before volume allocation while preserving restoration when omitted.
• Adds unit and end-to-end regression coverage.
• Updates API descriptions, CLI documentation, and contributor guidance.

File	Description
src/​api/​openapi.yml	Documents rejection behavior for both creation endpoints.
src/​api/​impls/​sandbox.rs	Adds shared validation and unit coverage.
src/​api/​generated/​src/​models.rs	Updates generated field documentation.
scripts/​tests/​e2e/​suites/​15_volume.sh	Tests explicit and empty mounts on both endpoints.
docs/​src/​concepts/​volumes/​sandbox-forks-and-snapshots.md	Explains captured-volume launch restrictions.
docs/​src/​concepts/​sandboxes/​starting.md	Documents the CLI volume restriction.
CLAUDE.md	Aligns contributor guidance with the new behavior.

_{Review effort: Balanced}

[github-actions]

✅ OpenCodeReview: Review complete: 0 finding(s) across 3 selected item(s).