Run coding agents in sandboxed MicroVMs

Run Claude Code or Codex in an AWS Lambda MicroVM with a copy of your project. The agent can edit files and run tools as a non-root user in /workspace. Both profiles call Amazon Bedrock using a short-lived token minted from your AWS credentials.

Start with one agent

First install the CLI and configure AWS. You need AWS CLI v2, MicroVMs permissions, the artifact bucket and build/execution roles, and Bedrock invocation permissions with access to your chosen model. These commands create billable AWS resources. The first image build takes several minutes; later launches reuse it when its inputs are unchanged.

From your project directory:

microvm agent-up --vm-name review --agent claude-code --project .
microvm agent-prompt --name review \
  "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 file download verifies that the agent produced an artifact and saves it locally. A successful model response alone does not prove that files were changed. agent-up keeps the VM running; terminate --wait waits for termination. Its image stays available for the next agent VM.

Choose an agent and model

Agent	Launch flag	Default Bedrock model	Override
Claude Code	--agent claude-code	global.anthropic.claude-opus-5	--claude-model MODEL_ID
Codex	--agent codex	global.openai.gpt-5.6-sol	--codex-model MODEL_ID

Omitting --agent installs Claude Code. Repeat it to put both agents in the same VM, then select one on every prompt:

microvm agent-up --vm-name dev --agent claude-code --agent codex --project .
microvm agent-prompt --name dev --agent codex \
  "Create hello.py that prints hello from a microvm, run it, and show the output."
microvm cp --name dev vm:/workspace/hello.py ./hello.py
microvm terminate dev --wait

Use --claude-version VERSION or --codex-version VERSION on a fresh launch to pin the npm package. A changed version pin produces a different image name. To install a different agent set or package version, launch a new VM under a new name, or terminate the old VM first.

Move code and results

The following examples address a running VM named review; run agent-up again if you terminated it after the quickstart.

--project . uploads a copy into /workspace. It skips .git, target, node_modules, and .venv; other files are included. Install project dependencies in the guest as needed. The agent image already includes Node.js 22, npm, Python 3, Git, and basic shell tools.

While a named VM is running, upload an updated project with microvm agent-up --vm-name review --project .. This refreshes credentials and uploads files into the existing workspace. It does not rebuild the VM or reinstall the agent packages.

Copy individual outputs with microvm cp, as in the quickstart. For a directory of generated outputs, download an archive:

microvm cp --name review --tar vm:/workspace/dist ./dist.tar

The local destination is a tar file. Downloading all of /workspace also includes .agent-env, which contains the Bedrock bearer token; select your output files or output directory when collecting results.

Long tasks and VM lifetime

agent-prompt waits and collects output by default, with a 900-second caller wait limit. --timeout SECONDS changes only that wait; expiration leaves the remote agent running. --execution-timeout SECONDS sets a separate positive, finite daemon deadline that persists after the caller exits. To return immediately, start a detached task and poll its exec ID (this example uses jq):

ID=$(microvm agent-prompt --name review --execution-timeout 1200 --detach --json \
  "Run the test suite and write a summary to TESTS.md." | jq -r .data.execId)
microvm exec --name review --poll "$ID"
# After the exec finishes and you have collected its output:
microvm ack --name review "$ID"

Repeat the poll until the task finishes. Add --agent when the VM carries both agents. Detached tasks have no execution deadline unless you set --execution-timeout. The deadline signals the whole process group with SIGTERM, then SIGKILL after the daemon’s kill grace (10 seconds by default). The raw outcome reports timed_out; caller wait expiration is a separate timeout error and does not cancel the exec. Processes that leave the group require VM termination as the final cap.

Use --permission-mode unrestricted to bypass agent approval prompts inside the VM; the default remains agent-default. Both modes run as uid/gid 1000 and retain the VM’s existing IAM role and routing. --reap-group-on-exit stops residual test servers and fuzzers after the agent exits; it is off by default. Reports include the selected mode, UID, model and actual installed agent version.

Python timeout_sec and TypeScript timeoutSec on asynchronous prompt methods set the remote deadline. Their prompt_sync / promptSync convenience methods currently couple the wait and execution budgets (timeout in Python, timeoutSec in TypeScript). Rust PromptOptions.timeout sets the remote budget; ExecHandle::wait takes its own wait budget.

Detach alone does not keep a VM running after the laptop closes. The external runner must own health checks, artifact collection, cancellation and cleanup.

Setting	Default	Effect
--memory	1024	1 GiB billing baseline, 4 GiB guest ceiling
--max-idle-sec	600	Suspend after this many seconds without inbound traffic
--suspended-sec	600	Terminate a VM the idle policy suspended after this many seconds suspended
--max-duration-sec	3600	Maximum VM lifetime; upper limit is 28800 seconds (8 hours)
--auto-resume	off	Let an inbound request wake a suspended VM
--token-ttl-hours	12	Maximum Bedrock token lifetime; signing credentials may expire sooner

Choose lifetime settings on the initial agent-up. For multi-hour work, raise --max-duration-sec and keep inbound traffic active by polling microvm health --name review at intervals below --max-idle-sec. A VM the idle policy suspended is terminated --suspended-sec after it suspends, and --auto-resume cannot bring a terminated VM back. A busy process inside the guest does not count as inbound traffic. Suspend and resume explains the lifecycle in more detail.

If credentials expire while the VM is still alive, refresh them:

microvm agent-up --vm-name review

This reads the installed-agent marker and rewrites the credential files. It keeps the existing agents and models, builds nothing, and does not extend the VM’s lifetime. For a model change on an installed agent, name that agent explicitly with its model override; include both agent flags when keeping both profiles. Refresh does not install missing packages.

Isolation and credentials

The agent runs as uid/gid 1000 in the guest. Claude Code’s headless profile permits Bash,Read,Edit,Write,Grep,Glob; Codex uses workspace-write. The token is installed after launch in /workspace/.agent-env with mode 0600, so it is absent from the shared image snapshot.

The agent VM has internet egress to reach Bedrock. VM isolation does not make it a network-isolated workload. Keep the execution role minimal: guest processes can access its credentials. For workloads requiring no internet egress, use the general sandbox flow with an existing VPC connector in a VPC without an internet gateway or NAT gateway. Omitting --egress does not block traffic, and --deny-egress is advisory. See Networking.

Cleanup, automation, and SDKs

Always terminate a kept VM when finished:

microvm terminate review --wait

Add --delete-image when you also want to delete its image. Snapshot storage has a one-week minimum charge even if you delete earlier. Inspect cleanup reports and data.leaked on failures; microvm ls --remote helps find remaining resources. See Costs.

Use --json to automate the same flow: agent-up returns a microvm.agent envelope and agent-prompt returns microvm.agent.prompt. Script and agent integration covers errors, polling, and streaming.

For programmatic use, start with the complete Python, Node.js/TypeScript, and Rust examples. The Python and Node packages also expose AgentVm for building agent images, launching, installing credentials, and prompting. The Agent VMs guide documents those methods, profiles, and provisioning details. The shell example shows the individual build, launch, file-transfer, and exec steps.