microvm build

1. Synopsis

Build a MicroVM image and wait for it to be usable

microvm build [binary] [options]

2. Parameters

Parameter	Kind	Type	Required	Default	Choices	Help
binary	positional	path	no	none	any	The aarch64 agentd binary to bake in as the image CMD
--state-dir	flag	path	no	none	any	Where the provisioned-daemon cache lives. Defaults to $MICROVM_STATE_DIR or ~/.microvm/runs — the same directory run’s ledger uses, so the two commands share one cache
--artifact-uri	flag	string	no	none	any	Where the build artifact already is, as an s3:// URI. See run --artifact-uri
--name	flag	string	no	none	any	Image name. Defaults to a per-invocation name
--memory	flag	enum	no	2048	512, 1024, 2048, 4096, 8192	Baseline MiB, selecting a documented size class
--cpus	flag	string	no	none	any	vCPUs the workload needs, instead of --memory: the smallest size class whose baseline covers the request is used. Takes a fraction (0.5) and combines with --memory-mib
--memory-mib	flag	string	no	none	any	MiB of memory the workload needs, instead of --memory: any figure, which selects the smallest class whose baseline covers it (1500 selects 2048). Combines with --cpus
--dockerfile	flag	path	no	none	any	A Dockerfile to use instead of the library’s default
--project	flag	path	no	none	any	A project directory whose dependency files bake an environment layer into the image (#74)
--base-image-version	flag	string	no	none	any	Pin the managed base image to one version instead of taking the service’s default
--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>. See run --log-group
--log-stream	flag	string	no	none	any	Log stream name prefix inside --log-group. The client appends /<16 hex> per build attempt and the envelope reports the resolved exact name as logStream. See run --log-stream. Requires --log-group — build reads no config file, so the flag is the only place a group can come from
--repair-identity	flag	boolean	no	none	any	Widen the guest so sethostname and the boot_id bind mount work
--tag	flag	string	no	none	any	A tag on the image, repeatable. Split at the first =, so a VALUE may hold one, and checked against the model’s TagKey and TagValue at parse time; an empty VALUE is legal. A KEY given twice is refused rather than one of its values dropped
--base-image	flag	string	no	none	any	The managed base image baseImageArn names, instead of al2023-1
--inherit-workdir	flag	boolean	no	none	any	Rely on the image’s WORKDIR: an exec with no cwd runs there
--run-hook-timeout-sec	flag	string	no	none	any	The timeout of the run, resume, suspend and terminate hooks, in whole seconds
--build-hook-timeout-sec	flag	string	no	none	any	The timeout of the ready and validate build hooks, in whole seconds
--reuse	flag	boolean	no	none	any	Reuse an existing image whose build inputs match, instead of building
--s3-key-prefix	flag	string	no	none	any	Under --reuse, a key prefix inside the bucket for the artifact
--force	flag	boolean	no	none	any	Under --reuse, delete a ready image under the derived name and build it afresh
--port	flag	string	no	none	any	The daemon’s port inside the guest
--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
--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.image. Its data object carries these keys: imageIdentifier, imageName, buildLogGroup, logStream, size, reused, artifactUri, 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 build 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.