microagent start

Last updated: 2026-08-15

microagent start <name> [--state-dir <dir>]
microagent start <name> --wait [--wait-timeout <dur>]
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

Boot a created or halted workspace:

microagent start research

start reuses the resource config stored by create. Pass --profile, --memory, or --cpus only when you want a one-start override:

microagent start research --profile large

Resume in place from a snapshot:

microagent start research --from-snapshot pre-upgrade

After it’s running, open a console with connect or read serial output with logs.

start returns once the VM boots, not when the workload finishes. When the workspace runs something that ends on its own - an agent, a batch job - add --wait to block until it reaches a terminal state:

Human output shows boot preparation and VM start progress on stderr. Snapshot restore also identifies restore preparation and guest clock synchronization. With --wait, boot and workload waiting are separate completion lines. JSON and MCP output remain typed and do not include these human progress messages.

microagent start minimal-agent --wait
microagent --json result minimal-agent

With --wait, the boot result is written first and a wait-shaped result follows when the run finishes. With the global --json flag that means two JSON documents on one stream; decode it as a stream, or run wait as its own command for a single document. The exit code is 0 for stopped/halted and 1 for failed/quarantined, exactly like microagent wait.

Flags

Common flags:

--wait - after boot, block until the workspace reaches a terminal state (--wait-timeout <dur> bounds it and implies --wait)
--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> - lifetime lease from VM start; activity does not renew it. 0 means permanent. Preserves a lease declared at create time
--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/`)
`--wait`	After boot, block until the workspace reaches a terminal state (stopped, halted, failed)
`--wait-timeout <dur>`	Give up waiting after this long (for example `5m`); `0` waits forever; implies `--wait`
`--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>`	Lifetime lease from VM start; activity does not renew it. `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 --output/--json/--supervisor.

start fails closed with the current count and limit when it would push the host past its workspace-count ceiling — see bounded operations.

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 terminal custody, not a restartable disk state. Its durable marker blocks both an ordinary start and --from-snapshot; another lifecycle verb cannot clear that marker.

A restore only reports running once the resumed guest proves it survived the load. If the guest crashes immediately after resume, start fails closed with a non-zero exit and points at the serial log. That replaces a crash surfacing later as an unrelated exec or connect failure.

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 (or its stop alias), 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

start exits 0 when the workspace boots; nonzero when it cannot be found, fails to boot, or is started from an invalid state. start rejects workspaces that are already starting or running, and refuses every workspace with a durable containment marker.

create - create the workspace first
wait - block until an already-started run finishes
halt - shut it down again (stop is an alias)
status - check state and readiness
snapshot - manage the tags --from-snapshot restores