microvm run

1. Synopsis

Build an image, launch a VM, run a command, report the cost, tear it down

microvm run [binary] [options]

2. Parameters

Parameter	Kind	Type	Required	Default	Choices	Help
binary	positional	path	no	none	any	A directory to sync (issue #72), or an agentd binary to bake in
--image	flag	string	no	none	any	Launch this existing image instead of building one. Takes an ARN or a name
--image-version	flag	string	no	none	any	Launch this exact image version instead of the image’s latest active one
--artifact-uri	flag	string	no	none	any	Where the build artifact already is, as an s3:// URI
--exec	flag	string	no	none	any	A shell command to run in the VM
--name	flag	string	no	none	any	Image name. Defaults to a per-invocation name, because reusing one is how a clientToken replay wedges an image
--memory	flag	enum	no	2048	512, 1024, 2048, 4096, 8192	Baseline MiB, which selects a documented size class
--cpus	flag	string	no	none	any	vCPUs the workload needs, instead of --memory: the smallest size class whose baseline covers the request is used. Takes a fraction (0.5) and combines with --memory-mib
--memory-mib	flag	string	no	none	any	MiB of memory the workload needs, instead of --memory: any figure, which selects the smallest class whose baseline covers it (1500 selects 2048). Combines with --cpus
--dockerfile	flag	path	no	none	any	A Dockerfile to use instead of the library’s default. Its FROM must match the base
--log-group	flag	string	no	none	any	CloudWatch log group for the build’s logs, instead of the service-created /aws/lambda-microvms/<image-name>
--log-stream	flag	string	no	none	any	Log stream name prefix inside --log-group. The client appends /<16 hex> per build attempt, and the resolved exact name is on the envelope as logStream
--repair-identity	flag	boolean	no	none	any	Widen the guest so sethostname and the boot_id bind mount work
--egress	flag	boolean	no	none	any	Request the managed INTERNET_EGRESS connector
--egress-network-connector	flag	string	no	none	any	Existing VPC network connector ARN. Repeat for multiple connectors
--deny-egress	flag	boolean	no	none	any	Set proxy environment variables that discourage outbound HTTP requests
--shell	flag	boolean	no	none	any	Launch shell-capable, so microvm shell can attach later
--launch-env	flag	string	no	none	any	Set one launch-environment variable for every exec in the VM, as KEY=VALUE. Repeatable
--user	flag	string	no	none	any	User to run --exec’s command as: a name or a numeric uid. Omitted runs as the image’s AGENTD_DEFAULT_USER, or as the daemon’s own user when the image sets none
--group	flag	string	no	none	any	Group to run --exec’s command as: a name or a numeric gid. Omitted keeps the daemon’s own group, or a named user’s primary group
--keep	flag	boolean	no	none	any	Leave the VM and image running. You are then paying for them
--no-wait	flag	boolean	no	none	any	Return once the launch is accepted, with the VM still PENDING, instead of waiting for RUNNING and for its daemon. microvm wait finishes the launch later
--identity	flag	boolean	no	none	any	Generate a per-VM identity, so tunnel --verify-identity can prove the far end
--vm-name	flag	string	no	none	any	Register a local name for the kept VM, so later commands can say --name <NAME> instead of pasting the endpoint/agent-token/microvm-id triple
--client-token	flag	string	no	none	any	Idempotency key for this launch: 1-128 printable ASCII characters
--vm-log-group	flag	string	no	none	any	CloudWatch log group for the VM’s own logs (not the image build’s)
--vm-log-stream	flag	string	no	none	any	Exact log stream inside --vm-log-group
--no-vm-logs	flag	boolean	no	none	any	Turn the VM’s own logging off
--timeout	flag	string	no	300	any	How long to wait for the exec, in seconds
--max-idle-sec	flag	string	no	600	any	Suspend the VM after this much inbound-traffic idleness
--suspended-sec	flag	string	no	600	any	Terminate a VM the idle policy suspended once it’s been suspended this long. An explicit suspend outlasted it when measured (2026-10-12), which AWS doesn’t promise
--auto-resume	flag	boolean	no	none	any	Let the platform resume a suspended VM on an incoming request
--max-duration-sec	flag	string	no	3600	any	Hard ceiling on the VM’s life. Refused above 28800 (eight hours) before any call
--port	flag	string	no	none	any	The daemon’s port inside the guest
--state-dir	flag	path	no	none	any	Where the run ledger is written. Defaults to $MICROVM_STATE_DIR or ~/.microvm/runs
--config	flag	path	no	none	any	Read this project config file instead of ./microvm.toml
--no-config	flag	boolean	no	none	any	Ignore any microvm.toml, even a malformed one. Flags and defaults apply
--region	flag	string	no	none	any	AWS region. Defaults to $AWS_REGION, then $AWS_DEFAULT_REGION, then us-east-1
--unlisted-region	flag	string	no	none	any	Deprecated since 1.3.0: --region takes any region name
--bucket	flag	string	no	none	any	S3 bucket for the build artifact. Defaults to $MICROVM_BUCKET
--build-role-arn	flag	string	no	none	any	Build role ARN. Defaults to $MICROVM_BUILD_ROLE_ARN
--execution-role-arn	flag	string	no	none	any	Execution role ARN. Defaults to $MICROVM_EXECUTION_ROLE_ARN

The 3 global flags (--json, --dense, --quiet) are accepted here as on every command, and are left out of the table above for that reason; see Global flags.

3. Response

On success stdout carries one envelope whose type is microvm.run. Its data object carries these keys: imageIdentifier, imageName, microvmId, endpoint, agentToken, execExitCode, stdout, stderr, truncated, buildSeconds, runningSeconds, kept, vmName, leaked, cost, egressPosture, imageReused, artifactUri, resolvedConfig, configPath, sync, agentd.

The envelope describes the fields around data. Response types lists every type the CLI emits and which commands share each one.

4. Failures

A failure exits with one of the statuses on Exit codes and writes the error shape on The envelope: a stable code to branch on, an exitCode that matches the process status, a human-readable error, and suggestions.

Where a failure is one this project has measured on the platform, the envelope’s finding names the section of the platform notes that documents it. The exit-code table links each one.

5. Provenance

This page is generated from docs/manifest.json, the output of microvm manifest, which the CLI derives from its own argument tree. This page reads the run entry of data.commands. site/scripts/gen-reference.mjs writes it into the site’s content directory on every pnpm run sync, so an edit made here is overwritten by the next run.

To change the page, change the source. Regenerate the source with mise run manifest from the repository root; mise run manifest:check fails when the committed file no longer matches what the binary emits.