microvm exec

1. Synopsis

Run one command in a MicroVM that is already running

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
--timeout-sec	flag	string	no	none	any	The daemon’s deadline for the command, in seconds: timeout_sec on the start request
--complete	flag	boolean	no	none	any	Wait for exactly one result, the way the SDKs’ run_to_completion does (BIND-8 to BIND-10)
--client-grace	flag	string	no	none	any	With --complete, the seconds past --timeout-sec before the kill, and then for its result
--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	User to run the 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 the command as: a name (resolved against the guest’s /etc/group) or a numeric gid. Omitted keeps the daemon’s own group, or a named user’s primary group
--shell	flag	string	no	none	any	Run the command under this shell instead of /bin/sh, for example bash (AGENTD-14)
--inherit-image-env	flag	boolean	no	none	any	Start the command’s environment from the image’s ENV rather than from nothing (AGENTD-11)
--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
--poweroff-on-exit	flag	boolean	no	none	any	Power off the guest after this exec’s original process group exits. Requires a supporting daemon with CAP_SYS_BOOT. Other work ends too; start acknowledgment and results may race shutdown. Does not prevent idle suspend
--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. Prefer --name or --agent-token-file
--agent-token-file	flag	path	no	none	any	Read the agent token from a protected file, or from stdin with -. On Unix, the file must grant no permissions to group or other users
--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	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

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

The envelope describes the fields around data. 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 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 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.