Skip to content
docs.microagent.sh

microagent events

Last updated: 2026-08-15

microagent events <name> [--follow] [--state-dir <dir>]

events prints the recorded lifecycle events for a workspace, oldest first. Structured output also joins retained constraint, egress, broker, and secret-access records into the workspace trajectory. Most text events are state transitions (prepared, starting, running, halted, stopped, quarantined, failed) with their timestamp and a short detail. The lifecycle history is the same bounded events.json history described in State and identity. It is the history view: status answers what state the workspace is in now, result returns the guest’s completion payload, and events shows how the workspace got here.

Workspaces paired with host model runners also append model-worker markers when the runner is attached or released. These entries keep the same identity, state, timestamp, and detail shape as lifecycle events, with details such as model_worker=attached or model_worker=released. The detail records model and runner metadata needed for operator tracing, including the runner config digest, but not runner environment values.

By default events prints the recorded history once. With --follow (-f) it prints the history and then streams new events as the workspace changes state. It returns when the workspace reaches a terminal state (prepared, halted, stopped, quarantined, or failed) or you interrupt with Ctrl-C. With the global --json flag, events returns the joined host-owned trajectory: lifecycle, constraint, egress mediator, broker, and secret-access records ordered by parsed timestamps. Each envelope names its source and carries the available runtime, session, request, event, and operation IDs. --follow is not supported with JSON output.

Follow mode may show one delayed connection indicator on stderr. It stops before recorded or new events are written and never mixes spinner frames into the event stream.

Lifecycle envelopes carry purpose and correlation_id when supplied by the caller. Create, run, and dispatch accept --purpose; lifecycle mutation commands accept --reason and record it in the same purpose field. The text is opaque: microagent records and returns it but never treats it as authority or infers behavior from it.

Examples

Section titled “Examples”

Show the recorded history:

Terminal window
microagent events research
2026-06-01T00:00:00Z  prepared  workspace state/config exists but runtime is not started
2026-06-01T00:00:00Z  starting   model_worker=attached model_ref=hf.co/example/model.gguf engine=runner pid=1234 runner_config_digest=sha256:abc... holder=research model_url=http://127.0.0.1:6017/v1
2026-06-01T00:00:01Z  running   runtime is started
2026-06-01T00:00:09Z  halted    clean disk-preserving shutdown completed
2026-06-01T00:00:09Z  halted    model_worker=released model_ref=hf.co/example/model.gguf holder=research

Follow a workspace through start and shutdown:

Terminal window
microagent events research --follow

Flags

Section titled “Flags”

Add --follow to watch transitions live instead of reading the history once.

Flag Description
--follow, -f Stream new events until the workspace reaches a terminal state or you interrupt
--state-dir <dir> State directory holding the workspace record (default ~/.microagent/)

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

Exit status

Section titled “Exit status”

events exits 0 when the workspace record is found and read; nonzero when the workspace cannot be found or --follow is combined with JSON output.

Section titled “Related”
  • status - the current state and readiness
  • result - the completion payload
  • logs - serial console output