microagent pause
Last updated: 2026-08-27
microagent pause <name> [--reason <text>] [--state-dir <dir>]pause freezes a running workspace and records its state as paused. The VM’s
vCPUs stop executing, but guest memory, the workspace rootfs, attached disks,
identity, and events.json are all preserved. The runtime process keeps
running and the host-side network, port forwarding, and vsock paths stay in
place, so the workspace can be resumed in place with resume.
The command uses the delayed terminal progress contract documented for
halt. Short freezes finish without an indicator; JSON and MCP
responses remain structured.
This is memory pause, not a disk-preserving shutdown. Unlike halt,
a paused workspace keeps its live memory state; resume continues exactly where
it left off rather than booting again.
While a workspace is paused, exec, connect,
and stats are rejected with a message directing you to resume
it first.
On Linux with the currently pinned Firecracker (v1.16.x), exec and the
model bridge stop answering after a bare pause/resume cycle — see
Troubleshooting: exec times out after pause then resume on Linux.
pause requires the workspace to be running.
Examples
Section titled “Examples”Freeze a workspace, then thaw it:
microagent pause researchmicroagent resume research--state-dir matters only when the workspace lives outside the default
~/.microagent/.
| Flag | Description |
|---|---|
--name <name> |
Workspace name; positional name is also accepted |
--id <id> |
Workspace ID alias for --name |
--reason <text> |
Opaque reason recorded as the lifecycle event’s purpose |
--state-dir <dir> |
State directory holding the workspace record (default ~/.microagent/) |
--backend <name> |
Backend identity override |
--supervisor <path> |
Override the installed host backend supervisor path |
See global flags for --output/--json/--supervisor.
Exit status
Section titled “Exit status”pause exits 0 when the VM is frozen; nonzero when the workspace cannot be
found, is not running, or when the backend cannot freeze the VM.