microvm agent-up

1. Synopsis

Bring up a VM with a coding agent in it: image, launch, model credentials, non-root user

microvm agent-up [binary] --vm-name <string> [options]

2. Parameters

Parameter	Kind	Type	Required	Default	Choices	Help
binary	positional	path	no	none	any	The aarch64 agentd binary to bake in. Omitted provisions this CLI’s own release asset
--vm-name	flag	string	yes	none	any	The local name to register for the VM, and the handle every later command uses
--agent	flag	enum	no	none	claude-code, codex	Which agent to install. Repeatable; defaults to claude-code
--claude-model	flag	string	no	none	any	The Bedrock inference-profile id Claude Code uses. Defaults to the profile’s
--codex-model	flag	string	no	none	any	The Bedrock model id Codex uses. Defaults to the profile’s
--claude-version	flag	string	no	none	any	Pin the Claude Code npm package to this version. Changes the image’s reuse hash
--codex-version	flag	string	no	none	any	Pin the Codex npm package to this version. Changes the image’s reuse hash
--project	flag	path	no	none	any	A local directory to upload into /workspace after launch, packed the way run <DIR> packs
--memory	flag	enum	no	1024	512, 1024, 2048, 4096, 8192	Baseline MiB. Default 1024: a 4 GiB always-present ceiling at half the floor cost of 2048, which fits peaky agent sessions (see docs/AGENT-VMS.md)
--token-ttl-hours	flag	string	no	12	any	How long the Bedrock bearer token lives, in hours. Default and ceiling 12
--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 and name registry live. 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
--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.agent. Its data object carries these keys: vmName, microvmId, endpoint, agentToken, imageIdentifier, imageName, imageReused, vmReused, agents, credentialExpiresAt, workdir, project, egressPosture, 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 agent-up 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.