---
title: microvm exec
description: Run one command in a MicroVM that is already running
---

## 1. Synopsis

Run one command in a MicroVM that is already running

```sh
microvm exec [command] [options]
```

## 2. Parameters

| Parameter | Kind | Type | Required | Default | Choices | Help |
| --- | --- | --- | --- | --- | --- | --- |
| `command` | positional | `string` | no | none | any | A shell command to run in the VM. Omitted only with `--poll` |
| `--timeout` | flag | `string` | no | `300` | any | How long to wait for the command, in seconds |
| `--cwd` | flag | `string` | no | none | any | Working directory |
| `--env` | flag | `string` | no | none | any | Set one environment variable for the command, as KEY=VALUE. Repeatable |
| `--user` | flag | `string` | no | none | any | Numeric uid to run the command as. Omitted runs as the daemon's own user |
| `--group` | flag | `string` | no | none | any | Numeric gid to run the command as. Omitted keeps the daemon's own group |
| `--exec-id` | flag | `string` | no | none | any | Use this exec id instead of a fresh one, making a retry idempotent |
| `--poll` | flag | `string` | no | none | any | Read an existing exec's status and output instead of starting anything |
| `--detach` | flag | `boolean` | no | none | any | Start the command and return immediately, without waiting and **without acking** |
| `--stream` | flag | `boolean` | no | none | any | Stream output as it arrives rather than waiting for the whole thing |
| `--from-offset` | flag | `string` | no | none | any | Resume a stream at this byte offset. Only with `--stream` |
| `--stdin` | flag | `boolean` | no | none | any | Give the command a stdin pipe and feed it this process's stdin, then close it |
| `--reap` | flag | `boolean` | no | none | any | Signal the command's whole process group once its own child exits |
| `--kill-on-timeout` | flag | `boolean` | no | none | any | On `ERR_TIMEOUT`, stop the exec rather than leaving it running |
| `--endpoint` | flag | `string` | no | none | any | The VM's endpoint, as reported by `run` |
| `--agent-token` | flag | `string` | no | none | any | The agent token delivered to the VM at launch |
| `--microvm-id` | flag | `string` | no | none | any | The MicroVM id, needed to mint the endpoint proxy token |
| `--name` | flag | `string` | no | none | any | The name `run --keep --vm-name` registered, standing in for the whole triple |
| `--port` | flag | `string` | no | none | any | The daemon's port inside the guest |
| `--state-dir` | flag | `path` | no | none | any | Where the local state lives — the name registry, and exec's per-VM history. Defaults to $MICROVM\_STATE\_DIR or ~/.microvm/runs |
| `--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 |

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.exec`. Its `data` object carries these keys: `execId`, `exitCode`, `stdout`, `stderr`, `truncated`, `phase`.

[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.

### 3.1. With `--stream`

`--stream` changes what stdout carries: ndjson — one event object per line, then this envelope as the final line. The documented exception to the one-envelope rule: stream chunks are the command's output, not progress, so they cannot go on stderr.

The final line is an envelope whose `type` is `microvm.exec.stream`, with these keys in `data`: `execId`, `events`, `bytes`, `nextOffset`, `exitCode`, `truncated`, `gaps`.

## 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 `exec` 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.