AgentENV
CLAUDE.md3.7k starsChanged 4 months agoMITView on GitHub
AGENTS.md links to this file (CLAUDE.md); edit this shared source. AgentENV is a Rust workspace running snapshot-capable Firecracker sandboxes with an E2B-compatible API. Gateway and scheduler form a separate Go module in services/. Behavioral guidelines to reduce common LLM coding mistakes, combined with the project-specific instructions below. Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment. Don't assume. Don't hide confusion. Surface tradeoffs. Before implementing: - Read the affected module and its tests. Use the code…
Trending
Less talk lately.thin dataabout the whole repository
Who's talking about kvcache-ai/AgentENV
- A Hacker News story“AgentEnv”Hacker News · Jul 28, 2026 · 3 points
- A Hacker News story“AgentENV: A platform for running agent env at scale (Kimi K3 RL)”Hacker News · Jul 27, 2026 · 1 points
- kvcache-ai/firecracker“Fix/add kernel 6.18 network configs”GitHub · Nov 1, 2026
- nblintao/harbor“feat(environments): agentenv, an E2B backend that builds with aenv”GitHub · Sep 22, 2026
- radixark/miles“docs: add AgentENV API key authentication”GitHub · Aug 19, 2026
The biggest 5 of 9 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 9
Talked about on GitHub and Hacker News (9 times).
On GitHub · 7
- Nov 1, 2026Fix/add kernel 6.18 network configs — kvcache-ai/firecracker0 reactions
- Sep 22, 2026feat(environments): agentenv, an E2B backend that builds with aenv — nblintao/harbor0 reactions · 1 comment
- Aug 19, 2026docs: add AgentENV API key authentication — radixark/miles0 reactions
- Aug 5, 2026AgentENV, kvcache-ai, 2026.07 — AkihikoWatanabe/paper_notes0 reactions · 3 comments
- Aug 4, 2026AgentENV 完全解读:当大规模多 Agent 强化学习需要一台快照电脑 — vislee/leevis.com0 reactions
2 more on GitHub
- Jul 28, 2026Add AgentENV to Reference Implementations (Autonomous SWE Agents) — EthicalML/awesome-agentic-engineering-resources0 reactions
- Jul 27, 2026vm image: Dockerfile workflow — shazow/virtle0 reactions
On Hacker News · 2
- Jul 28, 2026AgentEnv3 points
- Jul 27, 2026AgentENV: A platform for running agent env at scale (Kimi K3 RL)1 point
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
30 rules. About 0 are common, 20 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈20
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Read the affected module and its tests.
- Distinctive: line 24
If multiple interpretations exist, present them.
- Distinctive: line 25
If a simpler approach exists, say so.
- Distinctive: line 26
If something is unclear, stop.
- Distinctive: line 32
No features beyond what was asked.
- Distinctive: line 33
No abstractions for single-use code.
- Distinctive: line 35
No error handling for impossible scenarios.
- Distinctive: line 36
If you write 200 lines and it could be 50, rewrite it.
- Distinctive: line 38
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
- Distinctive: line 45
When editing existing code:
- Distinctive: line 47
Don't "improve" adjacent code, comments, or formatting.
- Distinctive: line 48
Don't refactor things that aren't broken.
- Distinctive: line 50
If you notice unrelated dead code, mention it.
- Distinctive: line 53
When your changes create orphans:
- Distinctive: line 55
Remove imports, variables, and functions that YOUR changes made unused.
- Distinctive: line 56
Don't remove pre-existing dead code unless asked.
- Distinctive: line 81
Run the narrowest relevant checks during development, then the applicable repository checks below.
- Very specific: line 110
Run from the repository root.
- Very specific: line 133
Run builds/tests as a non-root user.
- Very specific: line 140
Use isolated AENV_TEST_STATE_DIR state and AENV_TEST_DEPS_PATH dependencies, never a live server's state.
- Very specific: line 153
Use Rust 2021, existing style, and tracing initialized only in binaries: info for lifecycle, debug for internals, warn for recoverable …
- Very specific: line 156
Use Conventional Commit prefixes (feat:, fix:, refactor:, ci:, chore:).
- Distinctive: line 158
Never push branches directly upstream.
- Distinctive: line 159
Use the PR template for pull requests and the appropriate issue template for issues, including CLI-created submissions.
- Very specific: line 190
Keep CapturedSandboxSnapshot alive until repository publication completes.
- Very specific: line 191
Storage: Commit logical layer references, not node-local paths.
- Very specific: line 197
Volumes: Keep reservations/readiness in VolumeManager and the repository.
- Very specific: line 204
Registries: Use configured regctl and ImageResolver.
- Very specific: line 217
Extensions: Start/patch failures fail the operation.
- Distinctive: line 247
Keep this guide concise; put implementation details in the linked docs or code.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AgentENV Agent Guide
AGENTS.md links to this file (CLAUDE.md); edit this shared source.
AgentENV is a Rust workspace running snapshot-capable Firecracker sandboxes with
an E2B-compatible API. Gateway and scheduler form a separate Go module in services/.
Behavioral Guidelines
Behavioral guidelines to reduce common LLM coding mistakes, combined with the project-specific instructions below.
Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.
1. Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing:
- Read the affected module and its tests. Use the code map and linked design docs to locate ownership boundaries.
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them; don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
2. Simplicity First
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
3. Surgical Changes
Touch only what you must. Clean up only your own mess.
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it; don't delete it.
- Preserve unrelated work already present in the checkout.
When your changes create orphans:
- Remove imports, variables, and functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
4. Goal-Driven Execution
Define success criteria. Loop until verified.
Transform tasks into verifiable goals:
- "Add validation" -> "Write tests for invalid inputs, then make them pass."
- "Fix the bug" -> "Write a test that reproduces it, then make it pass."
- "Refactor X" -> "Ensure tests pass before and after."
For multi-step tasks, state a brief plan:
1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
Run the narrowest relevant checks during development, then the applicable repository checks below. Report what ran and any checks blocked by missing hardware, permissions, dependencies, or credentials.
These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
Core Concepts
- Snapshot/template: A committed checkpoint contains VM state and references to memory, rootfs, attached-drive, and volume layers. Capture leaves the source running; launching it creates a new sandbox. Pause/resume retains the existing ID through separate paused-sandbox persistence. Template builds commit snapshots.
- Volume: An independently managed block filesystem that survives sandbox
deletion.
exclusivepermits one writable mount;ropermits shared read-only mounts.volumeMountsreferences managed volumes; cold-startattachedDrivesuses the same device machinery with a different ownership lifecycle. - OverlayBD/ublk: OverlayBD stacks immutable lower layers and an optional writable
upper; sealing turns changes into a reusable lower.
image.jsondescribes the stack, while layers hold data. ublk exposes it as a host block device for guest disks or memory restore; filesystem images and memory images are distinct. - OSS: The S3-compatible repository backend, including Alibaba OSS.
snapshot.repository_backendselectsossorposix_fs. Repositories own durable records and managed layers; external layers may stay in OCI registries. Runtime configs and download caches are derived data. P2P only accelerates access.
Build and Validate
Run from the repository root. Makefile, Cargo.toml, and rust-toolchain.toml define current targets and tooling.
make # Rust build
make fmt # workspace formatting check
make clippy # all targets/features, -D warnings
make test-unit # selected unit and capability tests
make test # agent, envd, and storage suites
make test-agent-integration # includes snapshot OSS E2E tests
make test-ublk # includes OverlayBD and MinIO tests
cargo test -p agentenv --lib test_name # focused unit test
make -C services test # gateway and scheduler tests
make -C services fmt-check vet # Go lint
make start-server # build/install daemon and run serverFor Rust changes, run formatting, clippy, and relevant tests; aggregate test
targets do not cover every crate. For services/ changes, also run Go tests;
use go test ./... inside services/ for shared packages. Validate both languages
for scheduler protobuf changes. Documentation-only changes need diff/link/command
checks, not runtime suites.
Run builds/tests as a non-root user. Capability-dependent Make targets use
scripts/run-with-capabilities.sh to delegate
CAP_NET_ADMIN and CAP_SYS_ADMIN through sudo/setpriv. Reuse the Makefile's
runner/environment setup for filtered privileged tests. VM tests require Linux,
/dev/kvm, ublk, and network namespaces. make test-unit also includes ublk tests;
some suites need network access or object-storage services.
Use isolated AENV_TEST_STATE_DIR state and AENV_TEST_DEPS_PATH dependencies,
never a live server's state. Set AENV_CONFIG_PATH for non-default test configs.
Configuration and Conventions
- Configuration lives in
src/cfg.rsandconfig/default.toml; select a file withAENV_CONFIG_PATHor--config.AENV_HOME_PATHholds state/caches,AENV_RUNTIME_PATHtransient runtime state, andAENV_DEPS_PATHdownloaded assets. server --setup-host --runtime-user <user> --runtime-group <group>runs as root to configure host access/sysctls.server --setup-onlyprovisions packages/assets without VM access. Normal startup downloads assets and validates prerequisites.- KVM is default; PVM requires x86_64 and host-provided
kvm_pvm. AgentENV does not install/load it. Select the mode withAENV_VIRTUALIZATION_MODE. - Use Rust 2021, existing style, and tracing initialized only in binaries:
infofor lifecycle,debugfor internals,warnfor recoverable issues,errorfor unrecoverable failures. Update schemas/config/docs with contract changes. - Use Conventional Commit prefixes (
feat:,fix:,refactor:,ci:,chore:). Push to a fork; open PRs againsthttps://github.com/kvcache-ai/AgentENV/. Never push branches directly upstream. See CONTRIBUTING.md. - Use the PR template for pull requests and the appropriate issue template for issues, including CLI-created submissions. Fill required sections and report checks accurately.
Code Map
| Area | Start here |
| API and lifecycle | src/api/impls/, src/orchestrator/service.rs, src/sandbox/backend.rs |
| Firecracker and drives | src/sandbox/firecracker/, src/sandbox/ublk/, src/sandbox/extra_drive.rs |
| Snapshots and templates | src/snapshot/, src/template/ |
| Durable repository (OSS/POSIX) | src/repository/ |
| Volumes | src/volume/, src/api/impls/volumes.rs, src/api/impls/sandbox.rs |
| Layered storage | storage/overlaybd/, storage/ublk/, storage/ublk-daemon/, storage/util/ |
| Images and P2P | src/image/, src/p2p/, src/overlaybd/p2p/ |
| Control plane and metrics | services/, src/observability/ |
| CLI, guest, tooling | crates/aenv/, thirdparty/envd/, adev/ |
| Tests | tests/, crates/e2e-tests/, crates/test-support/, scripts/tests/ |
Reuse shared helpers: src/local_store.rs (LocalKvStore, explicit
LocalStoreDurability::{Memory, Wal, Sync}), crates/object-store-operator/
(S3/credentials), crates/linux-cap/, crates/shell-util/, and crates/warm-pool/.
storage/uffd-core/ is reference-only and excluded from the workspace.
Constraints to Preserve
- Layering: Top-level
src/modules must not depend on each other in a cycle (src/module_cycles.rstests this). Move shared data down rather than importing upward. - Lifecycle: Recoverable capture/fork errors restore
Running; terminal errors require teardown. Graceful shutdown persists sandboxes asPaused. KeepCapturedSandboxSnapshotalive until repository publication completes. - Storage: Commit logical layer references, not node-local paths. Cache GC
must not delete durable artifacts or live writable uppers. Use
UblkDeviceManager; preserve shared-memory device reference counts and COW. - Capture: Preserve sealing/restacking and attached-drive state. Template-build
compression (
[template_build]) is separate from ordinary memory compression ([memory_snapshot]); ordinary captures keep rootfs layers raw. - Volumes: Keep reservations/readiness in
VolumeManagerand the repository. Reject deletion while mounted and new mounts whileuploading/failed. Fork exclusive volumes per child, share read-only volumes, and roll back failed child allocations. Snapshots storevolume_snapshotsseparately from attached drives; launches recreate volumes and reject explicitvolumeMounts(including empty arrays) for snapshots that have volumes. Deleting a source volume must not invalidate committed snapshots. - Registries: Use configured
regctlandImageResolver. Preserve lazy reads for OverlayBD-native images. Private registries use the runtime user's Docker credentials. Preserve OSS object-storage/source-registry publication policies;aenv-snapshot-imageexports rootfs only and must verify registry conflicts. - P2P: Depend on
P2pTransport. Reuse layer identity fromsrc/overlaybd/p2p/artifact.rs. Publish snapshot artifacts after repository commit, best-effort. OSS resolves fixed artifacts P2P-first; POSIX must not repair missing files from peers. Scheduler stores artifact-to-node hints only. - Scheduler: Assignments/heartbeats own bindings; lifecycle events are best-effort and do not establish bindings. Fork events identify each child. Redis query-only replicas serve existing-sandbox lookups; scheduling still requires the primary.
- Extensions: Start/patch failures fail the operation; stop is best-effort,
including pause. Pair start/stop with a per-runtime
sandboxInstanceId. Forward patches verbatim, store returned full params, and preserve them across snapshots/resume. Empty params work with hooks disabled; non-empty params do not.
Generated Code
Edit schemas and regenerate; include both changes. Handwritten thirdparty/
code is editable; generated clients/stubs are machine-managed.
| Schema | Regenerate |
src/api/openapi.yml | make agentenv-server |
src/custom_extension_api/openapi.yml | make custom-extension-client |
thirdparty/firecracker-client/firecracker.yaml | make firecracker-client |
thirdparty/envd/http-client/envd.yaml | make envd-http-client |
services/api/proto/scheduler.proto | make -C services proto; Rust regenerates via build.rs |
cargo adev codegen runs all OpenAPI generators. Prune orphaned custom-extension
models after schema removals. Firecracker upgrades also require matching binary
packaging, config/deps_manifest.toml, and the
sandbox testing checklist.
Details by Topic
- Architecture and persistence ownership.
- Snapshots, volumes, and template testing.
- P2P, control plane, and custom extensions.
- Configuration and environment variables.
Keep this guide concise; put implementation details in the linked docs or code.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

