Skip to content

feat: enable virtio-mem for firecracker - #216

Draft
RuoqingHe wants to merge 6 commits into
kvcache-ai:mainfrom
RuoqingHe:enable-virtio-mem-for-fc
Draft

feat: enable virtio-mem for firecracker#216
RuoqingHe wants to merge 6 commits into
kvcache-ai:mainfrom
RuoqingHe:enable-virtio-mem-for-fc

Conversation

@RuoqingHe

Copy link
Copy Markdown

What

Add hard virtio-mem memory resize support to Firecracker-backed AgentENV
sandboxes.

Why

AgentENV currently treats sandbox memory as fixed after boot. Firecracker
supports virtio-mem, but AgentENV does not expose a validated or
lifecycle-aware way to grow and shrink guest memory.

Related issue

Scope and non-goals

Included:

  • Firecracker virtio-mem hard resize.
  • Sandbox and orchestrator lifecycle integration.
  • Public memory resize and status endpoints.
  • Snapshot and legacy manifest compatibility.

Design and behavior changes

Public API

The PR adds:

  • GET /sandboxes/{sandboxId}/memory
  • PATCH /sandboxes/{sandboxId}/memory
    Responses distinguish:
  • Requested memory.
  • Observed plugged memory.
  • Converged state.
  • Partial or unknown state.
  • Unsupported legacy backends.
  • Invalid requests.
  • Lifecycle conflicts.
  • Gateway timeout.

Compatibility and operations

  • Public API or generated protocol:
  • Configuration or defaults:
  • Snapshot manifest, artifact layout, or storage format:
  • Upgrade and rollback:
  • Host requirements, permissions, ports, or dependencies:

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

Commands and results:


Skipped checks and reasons:

Risks and reviewer notes

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.

Add firecracker virtio-mem geometry and resize policy.

Alignment, ranges, and Firecracker integer boundaries validated.

Signed-off-by: Ruoqing He <ruoqing.he@moonshot.ai>
@RuoqingHe RuoqingHe changed the title Enable virtio-mem for firecracker feat: enable virtio-mem for firecracker Aug 26, 2026
Add virtio-mem device geometry and requested size to Firecracker state.

The device should be applied before fresh boot and validate it during
restore.

Signed-off-by: Ruoqing He <ruoqing.he@moonshot.ai>
Add validated PUT, PATCH, and GET operations for virtio-mem.

Expose requested and plugged status for convergence polling.

Signed-off-by: Ruoqing He <ruoqing.he@moonshot.ai>
Add sandbox resize operations with convergence and deadlines.

Serialized resizing with snapshot capture and retain rollback evidence.

Exposed backend resize results to lifecycle callers.

Signed-off-by: Ruoqing He <ruoqing.he@moonshot.ai>
Define memory resize and status endpoints in the OpenAPI schema.

Describe target, observed, convergence, timeout, and unsupported states.

Signed-off-by: Ruoqing He <ruoqing.he@moonshot.ai>
Generate request, response, client, and server bindings for memory
resize with command `cargo adev generate server`.

Keep generated API types aligned with the OpenAPI contract.

Signed-off-by: Ruoqing He <ruoqing.he@moonshot.ai>
@RuoqingHe
RuoqingHe force-pushed the enable-virtio-mem-for-fc branch from d648124 to 8fa8e89 Compare August 26, 2026 12:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant