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
--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	Numeric uid to run --exec’s command as. Omitted runs as the daemon’s own user
--group	flag	string	no	none	any	Numeric gid to run --exec’s command as. Omitted keeps the daemon’s own group
--keep	flag	boolean	no	none	any	Leave the VM and image running. You are then paying for them
--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
--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 the VM after this long suspended. A resume past it cannot work
--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	enum	no	none	us-east-1, us-east-2, us-west-2, eu-west-1, ap-northeast-1	AWS region. Defaults to $AWS_REGION, then $AWS_DEFAULT_REGION, then us-east-1
--unlisted-region	flag	string	no	none	any	Use a region this client has not seen carry MicroVMs. Costs you the diagnostic
--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, 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.