microagent start
Last updated: 2026-06-27
microagent start <name> [--state-dir <dir>]microagent start <name> --from-snapshot <tag> [--state-dir <dir>]start boots a workspace that was previously created. The workspace must
exist in the state directory (default ~/.microagent/).
Start is disk-state resume, not memory resume. It boots from the persisted
workspace disk after prepared, halted, stopped, or failed. It rejects
workspaces that are already starting or running. To thaw a paused
workspace, use resume instead.
Examples
Section titled “Examples”Boot a created or halted workspace:
microagent start researchstart reuses the resource config stored by create. Pass --profile,
--memory, or --cpus only when you want a one-start override:
microagent start research --profile largeResume in place from a snapshot:
microagent start research --from-snapshot pre-upgradeAfter it’s running, open a console with connect or read
serial output with logs.
Flags you’ll actually use:
--from-snapshot <tag>- restore memory and disk from a snapshot instead of booting fresh--profile <name>/--memory <MiB>/--cpus <n>- one-start resource overrides; the stored config is the default--ttl <seconds>- idle TTL; the VM is reaped after this long with noexec/connectactivity (activity renews it).0(default) means permanent. Preserves a lease declared atcreatetime--state-dir <dir>- only when the workspace lives outside~/.microagent/
The complete set:
| Flag | Description |
|---|---|
--state-dir <dir> | State directory holding the workspace record (default ~/.microagent/) |
--from-snapshot <tag> | Restore the workspace in place from this snapshot tag |
--profile <name> | Resource profile override: tiny, small, medium, or large |
--memory <MiB> | Memory override for this start |
--cpus <n> | CPU count override for this start |
--ttl <seconds> | Idle TTL; the VM is reaped after this long with no exec/connect activity. 0 = permanent (preserves a create-time lease) |
--kernel <path> | Linux kernel path override |
--arch <arch> | Guest architecture |
--backend <name> | Backend identity override |
--vsock p=host:port | Add a vsock mapping for this start. Repeatable |
--model-runner <backend> | Model runner backend override for this start: llamacpp, vllm, or custom |
--model-gpu <mode> | Model runner GPU intent override: off, on, or auto |
--model-runner-model <id> | Backend model id override for runners such as vLLM |
--model-runner-served-model <name> | OpenAI-compatible served model name override for runners such as vLLM |
--model-runner-command <template> | Custom model runner command override for this start |
--model-runner-name <name> | Custom host model runner name override |
--model-runner-health-path <path> | Custom host model runner health probe path override |
--model-runner-arg <arg> | Extra model runner argument override. Repeatable |
--model-runner-env KEY=VALUE | Extra model runner environment for this start. Repeatable; values are not persisted |
--model-mediation <mode> | Model mediation mode override: off, local-allow, or policy |
--model-policy-file <path> | Structured model mediation policy file override |
--model-policy-url <url> | External model mediation policy endpoint override |
--model-policy-timeout <duration> | Model mediation policy timeout override |
--supervisor <path> | Override the installed host backend supervisor path |
See global flags for --json/--text/--output/--mode/--supervisor.
Resume in place from a snapshot
Section titled “Resume in place from a snapshot”start <name> --from-snapshot <tag> restores the workspace in place from a
snapshot instead of booting fresh: it rolls the workspace
rootfs back to the snapshot’s copy and loads the snapshot’s memory and device
state, so the guest resumes exactly where it was checkpointed. The snapshot’s
kernel must match the workspace kernel; the load is rejected on kernel skew.
In-flight guest connections do not survive a restore - outbound TCP and live vsock sessions (exec/shell/mediation) are reset and the guest process must reconnect. Stop the workspace before restoring it in place.
quarantined is intentionally distinct: host-side network, mediation, and
side-effect paths were severed while the runtime may still exist. Run halt,
stop, or kill first, then start from the preserved disk state.
Paired models
Section titled “Paired models”A workspace created with create --model stores the model ref,
model runner config, and model mediation config. Every start re-pairs it:
the host model runner is re-ensured (a missing blob is auto-pulled), the
workspace is registered as a holder, and the vsock bridge plus
MICROAGENT_MODEL_URL / OPENAI_BASE_URL are wired into the guest. The
--model-runner* and --model-mediation* flags override the stored pairing
for one boot. halt, stop, kill, and delete release the hold; a guest
that exits on its own keeps it until the next lifecycle verb, and
model stop reclaims it immediately. Attach and release
actions are recorded in the workspace events history as
model_worker=attached and model_worker=released markers.
Exit status
Section titled “Exit status”start exits 0 when the workspace boots; nonzero when it cannot be found,
fails to boot, or is started from an invalid state - it rejects workspaces that
are already starting or running, and refuses quarantined workspaces until
they are halted, stopped, or killed first. In AX mode these return structured
error envelopes (an invalid-state start maps to conflict).