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

Install

Interface	Install	First example
CLI	cargo binstall microvms-cli --no-confirm	Run an agent below
Python 3.11+	pip install microvms	Python quickstart
Node 22.13+	npm install 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.

Configure AWS

With the CLI installed, configure the resources used to build and launch a sandbox. A first image build takes several minutes.

You need AWS CLI v2, 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.

For jobs that continue after you disconnect, see the background coding agent example: a Lambda durable function turns a GitHub issue into a draft PR or reviews a pull request, with job state in DynamoDB.

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. The CLI and SDKs accept an image ARN or resolve an image name in the selected region. The examples use the returned ARN so the intended image is explicit. They use the 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 '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.

Stability

From 1.0.0, the command-line tool, packages, published crates, and daemon wire protocol follow the stability and deprecation policy.

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.
• Automate with the documented contracts; llms.txt indexes Markdown pages.
• Contribute: mise run check checks code; mise run docs:check checks documentation.

Documentation index · Apache-2.0 license