[PR #127] [MERGED] feat(sandbox): add E2B-compatible secure sandbox support #196

New issue

Closed

opened 2026-10-29 14:20:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:53 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/127
Author: @LSX-s-Software
Created: 8/5/2026
Status: ✅ Merged
Merged: 8/14/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/envd-access-token

📝 Commits (4)

6c889d7 feat(sandbox): generate envd access token for secure sandboxes
dd45ddd feat(sandbox): generate envd access token seed when unconfigured
244e2a5 fix(sandbox): reject overriding reserved MMDS fields
30340ae feat(sandbox): make shared access token seed optional

📊 Changes

53 files changed (+1539 additions, -131 deletions)

View changed files

📝 Cargo.lock (+2 -0)
📝 Cargo.toml (+2 -0)
📝 config/default.toml (+6 -0)
📝 crates/aenv/src/client/files.rs (+21 -3)
📝 crates/aenv/src/client/mod.rs (+6 -2)
📝 crates/aenv/src/client/sandboxes.rs (+31 -18)
📝 crates/aenv/src/commands/connect.rs (+11 -8)
📝 crates/aenv/src/commands/exec.rs (+2 -1)
📝 crates/aenv/src/commands/start.rs (+23 -7)
📝 crates/aenv/src/grpc/mod.rs (+36 -4)
📝 deploy/k8s/base/agentenv-daemonset.yaml (+6 -0)
📝 deploy/k8s/overlays/local-dev/kustomization.yaml (+10 -0)
📝 docs/src/SUMMARY.md (+4 -0)
📝 docs/src/concepts/sandboxes.md (+2 -0)
📝 docs/src/configuration/env-vars.md (+1 -0)
📝 docs/src/configuration/reference.md (+12 -0)
📝 docs/src/deployment/docker-compose.md (+5 -0)
📝 docs/src/deployment/kubernetes.md (+8 -0)
📝 docs/src/deployment/pvm.md (+3 -0)
📝 docs/src/deployment/static-multi-node.md (+4 -2)

...and 33 more files

📄 Description

What

Introduce end-to-end support for E2B-compatible secure sandboxes. When a sandbox is created with secure: true, AgentENV generates a sandbox-specific envd access token and enforces it across the complete sandbox lifecycle.

Add the optional secure sandbox create field and return envdAccessToken from create, get, connect, and fork responses.
Pass secure tokens through Firecracker MMDS and envd initialization, and attach them to internal HTTP, Connect, aenv CLI, and E2B SDK requests.
Give secure fork children independent tokens and preserve token identity across pause, server restart, and resume.
Persist the sandbox's secure mode while keeping legacy records non-secure by default.
Manage a persistent node-local token seed automatically for single-node installations, while allowing an explicit shared seed for multi-node deployments.
Document deployment secret requirements and exercise secure mode explicitly in the E2B Python, TypeScript, and code-interpreter compatibility suites.

Why

AgentENV did not previously implement the E2B secure sandbox contract. Current E2B SDKs create secure sandboxes by default, so compatibility requires AgentENV to return an envd access token and enforce it transparently for SDK and CLI operations.

Introducing secure support should not force existing or single-node users to add configuration before upgrading. AgentENV therefore creates and reuses a managed local seed when no explicit seed is supplied, while multi-node operators can configure one shared seed through their deployment secret mechanism.

N/A - no linked issue.

Scope and non-goals

In E2B semantics, secure authenticates envd control communication. This PR does not add authentication to arbitrary application ports or implement cross-node sandbox migration. The install script remains unchanged.

Design and behavior changes

Tokens are HMAC-SHA256 values derived from the effective seed and sandbox ID. The token itself is not persisted in sandbox metadata.
Firecracker MMDS stores only the token hash. /init receives the token in both X-Access-Token and the request body, matching envd's contract.
Internal envd clients and proxy routes supply or validate the token as appropriate.
Fork children derive tokens from their own sandbox IDs and cannot authenticate with the source sandbox's token.
Secure state is persisted with a serde default of false, so legacy sandbox records continue to restore as non-secure.
Explicit environment or TOML configuration takes precedence over managed state. Changing the effective seed rotates existing secure sandbox tokens.
Without an explicit seed, normal startup reads or atomically creates $AENV_HOME/secrets/sandbox-access-token-hash-seed. The directory is 0700, the file is 0600, and malformed, unreadable, symlinked, or unexpectedly missing state fails instead of rotating silently.
Concurrent startup uses no-clobber persistence and all contenders reuse the winning seed.

Compatibility and operations

Public API or generated protocol: Introduces optional secure request fields and optional envdAccessToken response fields. Omitting secure preserves the previous non-secure behavior.
Configuration or defaults: Adds optional [sandbox].access_token_hash_seed / AENV_SANDBOX_ACCESS_TOKEN_HASH_SEED; single-node startup auto-generates a persistent seed when unset.
Snapshot manifest, artifact layout, or storage format: No snapshot format change. Persisted sandbox metadata adds secure with a legacy default of false.
Upgrade and rollback: Existing users can upgrade without changing configuration. Preserve $AENV_HOME/secrets/sandbox-access-token-hash-seed once secure sandboxes exist; deleting or changing it invalidates their tokens.
Host requirements, permissions, ports, or dependencies: No new ports or host packages. Kubernetes runtime nodes require the documented agentenv-runtime-secrets Secret; the local-dev overlay provides a test-only value.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Skipped checks and reasons:

make -C services test was not run because services/ is unchanged.
Benchmarks were not run because this change affects startup secret handling and request authentication rather than snapshot or steady-state data paths.

Risks and reviewer notes

Review the API-to-envd token flow as one new end-to-end secure sandbox contract rather than as an isolated seed-management change.
Review src/sandbox/access.rs for managed-secret durability, permissions, and concurrent startup behavior.
Review fork and resume identity replacement to ensure a child or resumed runtime cannot retain stale token metadata.
Multi-node deployments must use the same explicit seed on every runtime node before cross-node recovery of a sandbox ID is introduced.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/127 **Author:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Created:** 8/5/2026 **Status:** ✅ Merged **Merged:** 8/14/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/envd-access-token` --- ### 📝 Commits (4) - [`6c889d7`](https://github.com/kvcache-ai/AgentENV/commit/6c889d7019f80e38ea2fc70397963375d9b97e80) feat(sandbox): generate envd access token for secure sandboxes - [`dd45ddd`](https://github.com/kvcache-ai/AgentENV/commit/dd45ddd5a8e6298fbbbf3ba399a3255126f8e0e6) feat(sandbox): generate envd access token seed when unconfigured - [`244e2a5`](https://github.com/kvcache-ai/AgentENV/commit/244e2a5abb9903b18b496b2ae46910cc85a1209d) fix(sandbox): reject overriding reserved MMDS fields - [`30340ae`](https://github.com/kvcache-ai/AgentENV/commit/30340ae353d17956ee3f03c017cbb0576004415a) feat(sandbox): make shared access token seed optional ### 📊 Changes **53 files changed** (+1539 additions, -131 deletions) <details> <summary>View changed files</summary> 📝 `Cargo.lock` (+2 -0) 📝 `Cargo.toml` (+2 -0) 📝 `config/default.toml` (+6 -0) 📝 `crates/aenv/src/client/files.rs` (+21 -3) 📝 `crates/aenv/src/client/mod.rs` (+6 -2) 📝 `crates/aenv/src/client/sandboxes.rs` (+31 -18) 📝 `crates/aenv/src/commands/connect.rs` (+11 -8) 📝 `crates/aenv/src/commands/exec.rs` (+2 -1) 📝 `crates/aenv/src/commands/start.rs` (+23 -7) 📝 `crates/aenv/src/grpc/mod.rs` (+36 -4) 📝 `deploy/k8s/base/agentenv-daemonset.yaml` (+6 -0) 📝 `deploy/k8s/overlays/local-dev/kustomization.yaml` (+10 -0) 📝 `docs/src/SUMMARY.md` (+4 -0) 📝 `docs/src/concepts/sandboxes.md` (+2 -0) 📝 `docs/src/configuration/env-vars.md` (+1 -0) 📝 `docs/src/configuration/reference.md` (+12 -0) 📝 `docs/src/deployment/docker-compose.md` (+5 -0) 📝 `docs/src/deployment/kubernetes.md` (+8 -0) 📝 `docs/src/deployment/pvm.md` (+3 -0) 📝 `docs/src/deployment/static-multi-node.md` (+4 -2) _...and 33 more files_ </details> ### 📄 Description ## What Introduce end-to-end support for E2B-compatible secure sandboxes. When a sandbox is created with `secure: true`, AgentENV generates a sandbox-specific envd access token and enforces it across the complete sandbox lifecycle. - Add the optional `secure` sandbox create field and return `envdAccessToken` from create, get, connect, and fork responses. - Pass secure tokens through Firecracker MMDS and envd initialization, and attach them to internal HTTP, Connect, aenv CLI, and E2B SDK requests. - Give secure fork children independent tokens and preserve token identity across pause, server restart, and resume. - Persist the sandbox's secure mode while keeping legacy records non-secure by default. - Manage a persistent node-local token seed automatically for single-node installations, while allowing an explicit shared seed for multi-node deployments. - Document deployment secret requirements and exercise secure mode explicitly in the E2B Python, TypeScript, and code-interpreter compatibility suites. ## Why AgentENV did not previously implement the E2B `secure` sandbox contract. Current E2B SDKs create secure sandboxes by default, so compatibility requires AgentENV to return an envd access token and enforce it transparently for SDK and CLI operations. Introducing secure support should not force existing or single-node users to add configuration before upgrading. AgentENV therefore creates and reuses a managed local seed when no explicit seed is supplied, while multi-node operators can configure one shared seed through their deployment secret mechanism. ## Related issue N/A - no linked issue. ## Scope and non-goals In E2B semantics, `secure` authenticates envd control communication. This PR does not add authentication to arbitrary application ports or implement cross-node sandbox migration. The install script remains unchanged. ## Design and behavior changes - Tokens are HMAC-SHA256 values derived from the effective seed and sandbox ID. The token itself is not persisted in sandbox metadata. - Firecracker MMDS stores only the token hash. `/init` receives the token in both `X-Access-Token` and the request body, matching envd's contract. - Internal envd clients and proxy routes supply or validate the token as appropriate. - Fork children derive tokens from their own sandbox IDs and cannot authenticate with the source sandbox's token. - Secure state is persisted with a serde default of `false`, so legacy sandbox records continue to restore as non-secure. - Explicit environment or TOML configuration takes precedence over managed state. Changing the effective seed rotates existing secure sandbox tokens. - Without an explicit seed, normal startup reads or atomically creates `$AENV_HOME/secrets/sandbox-access-token-hash-seed`. The directory is `0700`, the file is `0600`, and malformed, unreadable, symlinked, or unexpectedly missing state fails instead of rotating silently. - Concurrent startup uses no-clobber persistence and all contenders reuse the winning seed. ## Compatibility and operations - Public API or generated protocol: Introduces optional `secure` request fields and optional `envdAccessToken` response fields. Omitting `secure` preserves the previous non-secure behavior. - Configuration or defaults: Adds optional `[sandbox].access_token_hash_seed` / `AENV_SANDBOX_ACCESS_TOKEN_HASH_SEED`; single-node startup auto-generates a persistent seed when unset. - Snapshot manifest, artifact layout, or storage format: No snapshot format change. Persisted sandbox metadata adds `secure` with a legacy default of `false`. - Upgrade and rollback: Existing users can upgrade without changing configuration. Preserve `$AENV_HOME/secrets/sandbox-access-token-hash-seed` once secure sandboxes exist; deleting or changing it invalidates their tokens. - Host requirements, permissions, ports, or dependencies: No new ports or host packages. Kubernetes runtime nodes require the documented `agentenv-runtime-secrets` Secret; the local-dev overlay provides a test-only value. ## Validation - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [x] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [x] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Skipped checks and reasons: - `make -C services test` was not run because `services/` is unchanged. - Benchmarks were not run because this change affects startup secret handling and request authentication rather than snapshot or steady-state data paths. ## Risks and reviewer notes - Review the API-to-envd token flow as one new end-to-end secure sandbox contract rather than as an isolated seed-management change. - Review `src/sandbox/access.rs` for managed-secret durability, permissions, and concurrent startup behavior. - Review fork and resume identity replacement to ensure a child or resumed runtime cannot retain stale token metadata. - Multi-node deployments must use the same explicit seed on every runtime node before cross-node recovery of a sandbox ID is introduced. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:53 +00:00