microvm agent-prompt

1. Synopsis

Hand a coding agent in a running agent VM one task, headless, as the non-root user

microvm agent-prompt <task> [options]

2. Parameters

Parameter	Kind	Type	Required	Default	Choices	Help
task	positional	string	yes	none	any	The task, as prose. Passed to the agent’s headless command single-quoted for sh
--agent	flag	enum	no	none	claude-code, codex	Which installed agent to prompt. Omitted reads the guest marker and takes the one it names
--permission-mode	flag	enum	no	agent-default	agent-default, unrestricted	Guest agent permission policy. Unrestricted bypasses agent approvals, still as uid 1000
--execution-timeout	flag	string	no	none	any	Remote execution deadline in seconds; persists after detach. Must be positive and finite
--reap-group-on-exit	flag	boolean	no	none	any	Terminate residual process-group children when the main agent exits
--timeout	flag	string	no	900	any	Caller wait limit in seconds. Does not stop the agent when the wait expires
--detach	flag	boolean	no	none	any	Start the agent and return immediately, without waiting and without acking
--exec-id	flag	string	no	none	any	Use this exec id instead of a fresh one, making a retry idempotent
--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.agent.prompt. Its data object carries these keys: execId, agent, model, phase, exitCode, stdout, stderr, truncated, posixExitCode, notes, synthesized.

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 agent-prompt 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.