Repository navigation
feat(sandbox-adapter): add AWS Lambda MicroVMs provider - #395
Draft
NathanFlurry wants to merge 1 commit into
Draft
NathanFlurry wants to merge 1 commit into
NathanFlurry wants to merge 1 commit into
Conversation
📟 Pip-Boy ·
|
| package (linux-x64-gnu) | @latest |
base | this PR | Δ vs base | packages |
|---|---|---|---|---|---|
@rivet-dev/pi |
392.5 MB | 392.5 MB | 392.6 MB | +30.6 KB (+0.0%) | 220 (0) |
@rivet-dev/sandbox-adapter |
114.5 KB | 114.5 KB | 145.1 KB | +30.6 KB (+26.7%) | 1 (0) |
@sandbox-agent/cli-shared |
27.2 KB | 27.2 KB | 27.2 KB | 0 | 1 (0) |
@sandbox-agent/persist-indexeddb |
12.4 KB | 12.4 KB | 12.4 KB | 0 | 1 (0) |
@sandbox-agent/persist-postgres |
12.3 KB | 12.3 KB | 12.3 KB | 0 | 1 (0) |
@sandbox-agent/persist-rivet |
12.2 KB | 12.2 KB | 12.2 KB | 0 | 1 (0) |
@sandbox-agent/persist-sqlite |
12.3 KB | 12.3 KB | 12.3 KB | 0 | 1 (0) |
@sandbox-agent/react |
41.6 MB | 41.9 MB | 41.9 MB | 0 | 15 (0) |
acp-http-client |
6.7 MB | 6.7 MB | 6.7 MB | 0 | 3 (0) |
sandbox-agent |
31.0 MB | 31.0 MB | 31.0 MB | 0 | 8 (0) |
🧹 Rust dependencies
Skipped: this PR doesn't change any Rust code or dependencies.
🦀 Binaries
Skipped: this PR doesn't change any Rust code.
⏱ Timing
| job | wall time | slowest step |
|---|---|---|
zizmor |
16s | checkout · 9s |
changes |
21s | checkout · 15s |
footprint |
3m09s | Run pnpm --dir sandbox-agent install --frozen-lockfile · 1m01s |
⏭ self-test |
— | skipped |
⏭ hygiene |
— | skipped |
⏭ native · ${{ matrix.platform }} |
— | skipped |
report |
27s | checkout · 10s |
🔭 Full CI trace for this commit
One OpenTelemetry trace of CI and Pip-Boy for d7708f7: every job and step, with the sizes above attached. Run after CI finishes.
pnpm install --frozen-lockfile --filter 'pipboy...'
pnpm --filter pipboy pipboy trace --sha d7708f77d13bbf73e48b594d4decc333a007f11dAdd --otlp <url> to send it to any OTLP/HTTP collector.
Agent instruction: From a rivet-dev/agents checkout, run the commands above, then read the trace file the last command prints. List the slowest jobs and steps and explain where CI time went.
NathanFlurry
force-pushed
the
task-20261114-130155-96f64422-aws
branch
2 times, most recently
from
November 15, 2026 19:53
b08d21c to
3963eb4
Compare
Add @rivet-dev/sandbox-adapter/lambda-microvms. Each Actor gets one Lambda MicroVM, suspended while the Actor sleeps and terminated when it is destroyed. Lambda MicroVMs has no exec or file API, so the image runs Sandbox Agent and the provider drives its process and filesystem API through the MicroVM's HTTPS endpoint, with a cached auth token scoped to that port. A kill or timeout ends the command's whole process tree. `pnpm test:live` runs tests/lambda-microvms.live.test.ts against a real MicroVM. It builds a temporary MicroVM image first and deletes it afterwards, unless LAMBDA_MICROVMS_TEST_IMAGE names an existing one. CI never runs it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
NathanFlurry
force-pushed
the
task-20261114-130155-96f64422-aws
branch
from
November 15, 2026 19:54
3963eb4 to
d7708f7
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an AWS Lambda MicroVMs sandbox provider at
@rivet-dev/sandbox-adapter/lambda-microvms. AWS launched MicroVMs on 2026-06-22: each MicroVM is a Firecracker VM with suspend, resume, and terminate APIs and its own HTTPS endpoint.Lifecycle
RunMicrovm(create)with defaults for theHTTP_INGRESSconnector, an 8 hour max lifetime, and an idle policy (auto-suspend after 15 idle minutes, auto-resume on the next request).createcan be a function of the Actor context.GetMicrovm. ASUSPENDEDMicroVM getsResumeMicrovm, and aSUSPENDINGone is waited on first. A 404,TERMINATING, orTERMINATEDreturnsundefined, so the Actor gets a new MicroVM. The provider then polls/v1/healththrough the endpoint, because AWS saysstateis eventually consistent.SuspendMicrovm. Conflict and 404 are ignored.TerminateMicrovm. 404 is ignored.Commands and files
Lambda MicroVMs has no exec or file API. The only ways in are the image itself, the
/runhook, or the endpoint. Its shell WebSocket is undocumented and AWS says not to use it in production. So the image runs Sandbox Agent, and the provider calls Sandbox Agent's process and filesystem API through the endpoint:The Sandbox Agent HTTP client lives in its own internal module (
sandbox-agent-http.ts, not exported from the package) so the AWS-specific code stays small.The docs give this Dockerfile. It is zipped with the
aarch64musl binary (MicroVMs default to ARM64), uploaded to S3, and built withcreate-microvm-image. The docs list each step.Tests
tests/lambda-microvms.test.tsruns the provider end to end against a real Sandbox Agent server and an in-memory fake of the MicroVMs control plane. A local proxy stands in for the endpoint: it returns 403 without the rightX-aws-proxy-authandX-aws-proxy-portheaders and 502 before the server is up. The suite covers:The tests run only when
SANDBOX_AGENT_BINpoints to asandbox-agentbinary, so CI skips them. Locally, all 38 package tests pass with the 0.5.6 release binary. The abort test fails if the child walk is removed.On-demand live test
cd packages/sandbox-adapter pnpm test:live lambda-microvmsThis runs
tests/lambda-microvms.live.test.tsagainst a real MicroVM with the AWS credentials and Region from the environment. It first builds a temporary MicroVM image the way the docs describe: it downloads theaarch64Sandbox Agent binary (SANDBOX_AGENT_VERSION, defaultlatest), zips it with the Dockerfile, uploads the zip to a new S3 bucket, and creates a build role. All of that is deleted afterwards. SetLAMBDA_MICROVMS_TEST_IMAGEto an image ARN to skip the build. A full run takes about 3 minutes.CI never runs it.
vitest.config.tsexcludes*.live.test.ts, and onlyvitest.live.config.ts, used bypnpm test:live, includes it.@aws-sdk/client-s3and@aws-sdk/client-iamare new dev dependencies for the image build.Live run (us-east-1)
All 6 live tests pass on an image built from the Dockerfile above. The image build took about 3 minutes. The tests cover:
Fixed from the live run:
/proc/<pid>/task/<tid>/children, which the old tree kill read. It now finds children by the parent pid in/proc/*/stat, which works on any Linux kernel.GetMicrovmstill reportsRUNNINGfor about 3 s afterTerminateMicrovm, soconnectwaited the fullreadyTimeoutMson 502s. The readiness wait now rechecksGetMicrovmevery 5 s and returnsundefinedonce the MicroVM is gone. It has a new fake test.imageIdentifiermust be an ARN. A bare name fails withMalformed ARN.lambda:PassNetworkConnectoris not a documented action, so it is gone from the permissions list.curlduring the build.Known: Sandbox Agent runs as pid 1 in the MicroVM and does not reap orphans, so killed children stay zombies. They are dead and hold only a process table entry. Reaping belongs in Sandbox Agent, as a follow-up.
Still unverified:
suspendedDurationSeconds: 28800.Package and docs
@aws-sdk/client-lambda-microvms@^3.1169.0is an optional peer dependency. Adding it moves the lockfile's shared@aws-sdk/credential-provider-nodepeer from 3.972.84, which is deprecated, to 3.972.97.scripts/test-packed.mjschecks thatdist/lambda-microvms.jsis packed.examples/docs/sandboxes/lambda-microvms.ts. The quickstart is unchanged, because this provider needs an image built first.🤖 Generated with Claude Code