microvms-agentd

Run AI agents in sandboxed AWS MicroVMs from your terminal or application. Give a coding agent a copy of your project, let it edit files and run tools in a remote VM, and bring back the results. Use the microvm CLI or the Python, JavaScript/TypeScript, and Rust SDKs to launch sandboxes, execute commands, transfer files, stream output, and tear everything down.

VMs run in AWS Lambda MicroVMs; no local Docker daemon or hypervisor is needed. The bundled agentd daemon handles commands inside each VM.

Get started · CLI reference · SDK examples · Documentation

Start here

Humans: copy the prompt below into your coding agent of choice, or press an Open in badge above to prefill it in Claude Code, Cursor, ChatGPT, or Claude. Nothing runs until you send it. The prompt explains what AWS Lambda MicroVMs are, the gap this project fills, and where the documentation lives, then asks the agent to guide you from install to a first sandbox.

I want to use AWS Lambda MicroVMs: on-demand, isolated Firecracker VMs that I pay for per use, with no Docker daemon or hypervisor to run myself. Help me understand the service and get productive with it using microvms-agentd.

The service launches a VM from a container image and forwards one HTTPS endpoint to the image's CMD. It has no exec API and no file-transfer API, so on its own you cannot run a command in the VM or move files in and out. microvms-agentd fills that gap: `agentd` is a small daemon baked into the image, and the `microvm` CLI plus Python, JavaScript/TypeScript, and Rust SDKs talk to it. Together they build images, launch VMs, run commands, stream output, copy files both ways, run coding agents such as Claude Code or Codex against Amazon Bedrock inside the VM, report cost, and tear everything down while flagging leaked resources.

Resources, in order:
1. https://laithalsaadoon.github.io/microvms-agentd/llms.txt indexes the docs as raw Markdown. Follow its links rather than scraping HTML.
2. https://laithalsaadoon.github.io/microvms-agentd/agents.md has the automation rules: `microvm manifest`, `--json` envelopes, error codes, and cleanup checks.
3. https://docs.aws.amazon.com/lambda/latest/microvm-api/Welcome.html is the AWS API reference for the service itself.

Then: explain the concepts I need (images, VMs, sessions, execution roles, egress, cost) in a few paragraphs. Install the CLI (`cargo binstall microvms-cli --no-confirm`), run `microvm doctor`, and help me satisfy the AWS prerequisites it reports. Once `doctor` passes, choose the CLI or the SDK that fits my stack, get one sandbox running, and show me how to run a command, copy files in and out, and terminate the VM. Commands create billable AWS resources, so tell me before running anything that costs money.

Agents: start with llms.txt, which indexes the documentation as raw Markdown. Read agents.md for the automation rules, and the AWS Lambda MicroVMs API reference for the service this project drives.

Install

Interface	Install	First example
CLI	cargo binstall microvms-cli --no-confirm	Run an agent below
Python 3.9+	pip install microvms	Python quickstart
Node 22.13+	npm install @theagenticguy/microvms	JavaScript / TypeScript quickstart
Rust	cargo add microvms-core	Rust quickstart

The CLI command requires cargo-binstall. Without it, download a CLI binary for your OS from Releases, or compile with cargo install microvms-cli --locked. The CLI downloads and verifies its matching ARM64 Linux daemon automatically. See installation for supported hosts and source builds.

Start in 90 seconds

With the CLI installed and AWS resources ready, copy the configuration below and start a sandbox. The first image build takes several minutes; the 90-second path gets the workflow started, not AWS provisioning completed.

You need AWS CLI v2, gh or curl for the daemon download, configured AWS credentials, Lambda MicroVMs access, an S3 artifact bucket, and build/execution IAM roles. Replace these example values:

export AWS_REGION=us-east-1
export MICROVM_BUCKET=your-artifact-bucket
export MICROVM_BUILD_ROLE_ARN=arn:aws:iam::123456789012:role/microvm-build
export MICROVM_EXECUTION_ROLE_ARN=arn:aws:iam::123456789012:role/microvm-execution
microvm doctor

Need those resources first? The AWS setup guide includes a Terraform path and required permissions. Commands below create billable AWS resources.

Run a coding agent in a sandbox

Your AWS caller needs permission to invoke the selected Bedrock model, and your account needs access to it. From a project directory, run Claude Code:

microvm agent-up --vm-name review --agent claude-code --project .
microvm agent-prompt --name review --agent claude-code \
  "Review this project and write your findings to REVIEW.md."
microvm cp --name review vm:/workspace/REVIEW.md ./REVIEW.md
microvm terminate review --wait

The CLI builds or reuses an image, copies your project into /workspace, and runs the agent as a non-root user in the VM. Inspect the downloaded REVIEW.md for its findings. Terminate the VM when done, including after a failed task; agent-up keeps it alive for follow-up prompts. The reusable image is retained.

The CLI mints a short-lived Bedrock token from your AWS identity; no separate model-provider API key is needed. For Codex CLI, replace --agent claude-code with --agent codex in both commands. See the agent guide for model selection, both agents in one VM, and credential refresh.

Run any command

No model access is needed for a regular sandbox:

microvm quickstart

This builds an image, runs hello-world, reports the result and estimated cost, and attempts cleanup. For your own commands, build once and reuse the image:

microvm build --name agent-tools --json
microvm run --image agent-tools --exec "uname -m"
microvm run . --image agent-tools --exec "ls -la"

Expected architecture output: aarch64; the second run lists your uploaded project. Add your runtimes and dependencies with a custom image before running tests. run cleans up the VM by default; add --keep --vm-name dev to keep working with microvm exec --name dev "...", then microvm terminate dev --wait.

Use a sandbox from code

Copy data.imageIdentifier from the build output above into MICROVM_IMAGE. If you skipped that step, first run microvm build --name agent-tools --json. SDKs need the image ARN, rather than a name resolved by the CLI. They use the same AWS credentials and MICROVM_EXECUTION_ROLE_ARN configured above.

export MICROVM_IMAGE='paste-the-image-ARN-here'

JavaScript / TypeScript: after installing the npm package, save as sandbox.mjs and run node sandbox.mjs:

import { Region, Sandbox } from '@theagenticguy/microvms';

const vm = await Sandbox.create(Region.parse(process.env.AWS_REGION ?? 'us-east-1'));
try {
  const session = await vm.run({
    imageIdentifier: process.env.MICROVM_IMAGE,
    executionRoleArn: process.env.MICROVM_EXECUTION_ROLE_ARN,
  });
  const result = await session.runSync(['echo', 'hello from a sandbox']);
  process.stdout.write(result.stdout);
  process.stderr.write(result.stderr);
  if (!result.ok) process.exitCode = result.exitCode ?? 1;
} finally {
  console.error('Cleanup:', await vm.terminate());
}

Python: after installing microvms, save as sandbox.py and run python sandbox.py:

import os
import sys
from microvms import Region, Sandbox

vm = Sandbox(Region.parse(os.environ.get("AWS_REGION", "us-east-1")))
try:
    session = vm.run(
        image_identifier=os.environ["MICROVM_IMAGE"],
        execution_role_arn=os.environ["MICROVM_EXECUTION_ROLE_ARN"],
    )
    result = session.run_sync(["echo", "hello from a sandbox"])
    print(result.stdout, end="")
    print(result.stderr, end="", file=sys.stderr)
    if not result.ok:
        raise SystemExit(result.exit_code or 1)
finally:
    print("Cleanup:", vm.terminate().to_dict(), file=sys.stderr)

Both print hello from a sandbox and request VM termination. Check the cleanup report for failures or undeleted resources. For complete setup, agent prompts via AgentVm, file transfer, and streaming, see the SDK guide. Rust has a complete Cargo example.

Sandbox boundaries and cleanup

The agent works in a remote VM on the project copy you upload. agent-up enables outbound networking so agents can reach Bedrock. VM isolation does not mean internet isolation: omitting --egress does not disable internet access, and --deny-egress sets proxy variables that workloads can bypass. For enforced internet isolation, use a custom VPC connector with no IGW, NAT, or other internet route; see Networking.

Workloads can access the VM execution role's credentials through metadata, so give that role only permissions every workload may use. agentd does not isolate itself from a root workload. Agent credentials live inside the VM; copy back selected results instead of archiving the entire workspace. See Trust and Security.

Cleanup can fail. Inspect leaked in CLI JSON output or SDK cleanup reports, and use microvm ls --remote to check remaining resources. Images have a one-week minimum retention charge; reuse them. See costs and recovery.

Next steps

• Run a project and collect artifacts
• Use JSON and streaming in automation; microvm manifest describes the installed CLI.
• Build a custom image or embed agentd.
• Contribute: mise run check checks code; mise run docs:check checks documentation.

Documentation index · Apache-2.0 license