---
title: microvm run
description: Build an image, launch a VM, run a command, report the cost, tear it down
---

## 1. Synopsis

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

```sh
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](/microvms-agentd/reference/#3-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](/microvms-agentd/reference/envelope/) describes the fields around `data`. [Response types](/microvms-agentd/reference/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](/microvms-agentd/reference/exit-codes/) and writes the error shape on [The envelope](/microvms-agentd/reference/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.