microagent perf

Last updated: 2026-06-23

microagent perf boot [flags]               Measure boot time over iterations
microagent perf footprint <name> [flags]   Report backend process memory
microagent perf steady <name> [flags]      Sample steady-state memory over time

perf runs repeatable local measurements and reports structured results. boot creates disposable workspaces, waits for a guest command to complete, and reports per-iteration duration plus min/avg/max. footprint reports the host resident set size for the recorded backend process of a running workspace. steady samples that RSS over time for steady-state overhead reporting.

On windows-hyperv there is no host backend process to sample (the Host Compute Service owns the VM worker process); footprint and steady read the workspace’s HCS memory statistics instead, and the report’s pid is 0.

Examples

Measure three default boots:

microagent --json perf boot --iterations 3

Measure a pinned Ubuntu image with the tiny profile:

microagent --json perf boot \
  --image docker.io/library/ubuntu@sha256:<digest> \
  --profile tiny \
  --iterations 5

Report host RSS for a running workspace:

microagent --json perf footprint research

Sample steady-state RSS for one minute:

microagent --json perf steady research --duration 60 --interval 5

Commands

Command	Purpose
boot	Measure disposable workspace boot time
footprint	Report host process RSS for a running workspace
steady	Sample host process RSS over time

Flags

Use the global --json flag (before perf) for the structured measurement records shown in the examples above.

boot flags

Flags you’ll actually use:

• --iterations <n> - one boot is noise; run several to get a usable min/avg/max
• --image <ref> - pin the image (by digest) so runs are comparable over time
• --profile <name> - measure the VM size you actually run, not the default
• --exec <command> - move the finish line from “guest up” to “workload ready”
• --timeout <seconds> - fail a hung iteration instead of stalling the whole run

The complete set:

Flag	Description
--image <ref>	OCI image reference. Defaults to Python 3.13 slim
--exec <command>	Guest command used to mark boot completion. Defaults to true
--iterations <n>	Number of boot measurements. Defaults to 1
--profile <name>	Resource profile: tiny, small, medium, or large
--state-dir <dir>	State directory (default ~/.microagent/)
--timeout <seconds>	Per-iteration timeout
--mke2fs <path>	mke2fs binary path
--supervisor <path>	Override the installed host backend supervisor path
--network <mode>	Network mode for measured boots (user, isolated); empty uses the backend default. Isolated boots need no host network privileges

footprint flags

Flag	Description
--state-dir <dir>	State directory (default ~/.microagent/)

steady flags

Flag	Description
--duration <seconds>	Sampling duration. Defaults to 10
--interval <seconds>	Sampling interval. Defaults to 1
--state-dir <dir>	State directory (default ~/.microagent/)

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

Exit status

perf exits 0 when every measurement completes; nonzero when a boot iteration fails or times out, or when footprint/steady cannot find a running workspace process to sample. In AX mode a failure is written as a structured error envelope.

Related

• run - the one-shot path perf boot measures
• stats - live resource usage for one workspace
• host - host backend capabilities that affect boot time
• status - inspect a running workspace before footprint/steady