microagent result

Last updated: 2026-07-30

microagent result <name> [--state-dir <dir>]

result reads the guest result channel for one workspace and returns the completion payload - start/completion timestamps, exit code, stdout, stderr, and failure error when the guest reported one - separately from serial logs.

When the workload never ran at all, the payload carries start_error with the guest’s own diagnosis (a failed mount, an unresolvable command, a failed exec). An exit code with start_error set describes the environment, not the command: nothing the workload could change caused it. Callers that attribute failures should branch on start_error before reading exit_code. It answers what the guest command produced; use status for the workspace’s current state and readiness, and events for the lifecycle history that led there.

Examples

Read the result:

microagent --json result research

When a result is ready, the response carries it under result:

{
  "ok": true,
  "backend": "linux-kvm",
  "result": {
    "identity": { "runtimeID": "research", "role": "workload", "backend": "linux-kvm" },
    "resultPath": "/home/user/.microagent/workspaces/research/result.json",
    "startedAt": "2026-06-01T12:00:00Z",
    "completedAt": "2026-06-01T12:00:03Z",
    "exitCode": 0,
    "stdout": "ok\n"
  }
}

Flags

The global --json before the subcommand is the flag that matters here.

Flag	Description
--name <name>	Workspace name (also accepted as positional)
--id <id>	Workspace ID alias for --name
--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

result exits 0 when the workspace is found and the result channel is read; nonzero when the workspace cannot be found or no result has been delivered.

Related

• status - current state; includes result when ready
• events - the lifecycle history
• logs - the serial console output