microagent rootfs

Last updated: 2026-06-25

microagent rootfs build --image <ref> --out <path> [flags]   Build an ext4 rootfs from an OCI image

rootfs build pulls an OCI image and writes an ext4 disk image. Use it when you want to prepare a rootfs ahead of time or hand it to a workspace via create --rootfs; the normal run/create paths build the same rootfs for you.

By default, rootfs build only accepts images pinned by digest. Pass --allow-mutable to accept tag references - run and create accept both; this is the stricter path. See security for the rationale.

Examples

Build a rootfs from a digest-pinned image:

microagent rootfs build \
  --image docker.io/library/busybox@sha256:c4e5b27bf840ba1ebd5568b6b914f6926f3559b2ad4f505b1f37aae483b907d6 \
  --arch arm64 \
  --size-mib 64 \
  --mke2fs /opt/homebrew/opt/e2fsprogs/sbin/mke2fs \
  --out /tmp/busybox-rootfs.ext4

Hand the result to create:

microagent create \
  --id agent-1 \
  --kernel /tmp/kernel \
  --rootfs /tmp/busybox-rootfs.ext4 \
  --state-dir /tmp/microagent

build flags

Flags you’ll actually use:

• --image <ref> and --out <path> - the required pair: what to build from and where the ext4 image lands
• --size-mib <MiB> - size the disk up front; an image that doesn’t fit fails the build
• --arch <arch> - cross-build for a guest architecture other than the host’s
• --allow-mutable - accept a tag reference when you’ve decided digest pinning isn’t worth it for this build
• --keep-stage - keep the unpacked stage directory to debug what actually went into the image

The complete set:

Flag	Description
--image <ref>	OCI image reference
--out <path>	Output rootfs path
--os <os>	Target OS (default linux)
--arch <arch>	Target architecture (amd64, arm64)
--size-mib <MiB>	Disk size
--mke2fs <path>	mke2fs binary path
--exec <command>	Shell command to run as guest init
--init <path>	Guest init path to inject
--state-dir <dir>	Builder state directory
--keep-stage	Keep the temporary unpacked stage directory
--stage-snapshot <path>	Copy the unpacked stage directory to this path before ext4 creation
--allow-mutable	Allow tag references (image without a digest)

See global flags for --json/--text/--output/--mode.

For private registries, microagent resolves credentials without any Docker dependency: from $REGISTRY_AUTH_FILE (the convention shared with Podman/Skopeo/Buildah) or ~/.microagent/auth.json (written by microagent registry login). Credential helpers are never executed, Docker’s ~/.docker/config.json is never read, and public images always pull anonymously. See registry for the resolution order.

Exit status

rootfs build exits 0 when the rootfs is written; nonzero when the image cannot be pulled, the reference is a mutable tag without --allow-mutable, or the ext4 image cannot be created. In AX mode a failure is written as a structured error envelope.

Related

• create - consume the rootfs with --rootfs
• run - the one-shot path that builds this for you
• image - reusable cached rootfs baselines