Debug a failed run

Use this guide when holo run, holo mcp, or holo acp starts but does not finish the desktop task.

Quick checklist

Run through these first. Most first-run failures are one of them.

Check	Command or location	Success looks like
CLI is available	`holo --help`	Help prints without an import or command error
Hosted mode is ready	`holo whoami`	Your signed-in identity prints
Local mode is ready	`holo run --base-url http://localhost:8000/v1 ...`	The CLI reaches your local server and does not require login
Runtime is available	`holo doctor`	The `binary` row resolves a runtime path
Logs are written	`~/.holo/runs/` and `~/.holo/logs/`	Per-run and runtime logs appear after a task
Desktop permissions granted	Desktop permissions	The CLI can observe the screen and click and type
Stop works	`Esc` twice, `Ctrl+C`, `holo stop`, or cancel from the host	The active run stops or reports interrupted
App is on the primary display	Display settings	The CLI can see and control the app it needs

Start with doctor

holo doctor

holo doctor is read-only. It checks the runtime binary, hosted or local model credentials, the agent API port, and the ~/.holo directory. Fix the first failing check before moving on.

Reproduce with the CLI

If the failure happened from MCP or ACP, reproduce the smallest version from a terminal first:

holo run \
  --max-steps 5 \
  "Open TextEdit and write the word test"

For local mode, include the same base URL and model that the host uses:

holo run \
  --base-url http://localhost:8000/v1 \
  --model Hcompany/Holo-3.1-35B-A3B \
  --max-steps 5 \
  "Open TextEdit and write the word test"

If the CLI works but the host does not, check host configuration, environment inheritance, and workspace scope.

Stop a bad run first

If HoloDesktop CLI is acting in the wrong app, typing in the wrong place, or looping, cancel the active run before debugging. The fastest stop is pressing Esc twice quickly, a global kill switch that works even while Holo holds focus. You can also press Ctrl+C in the launching terminal, or run holo stop from any terminal (holo stop --force also kills the runtime). For MCP or ACP runs, run holo stop or cancel the request from the host. To bound runs ahead of time, pass --max-steps or --max-time-s.

Check model mode

For hosted mode:

holo whoami

If this fails, run:

holo login

For local mode, confirm the OpenAI-compatible endpoint is reachable:

curl http://localhost:8000/v1/models

Then retry HoloDesktop CLI with --base-url. Local mode does not require holo login.

Check host environment

MCP and ACP hosts launch HoloDesktop CLI non-interactively. Hosted mode needs HAI_API_KEY available to that process, usually from ~/.holo/.env after holo login. Local mode needs:

HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1

and sometimes:

HAI_AGENT_RUNTIME_MODEL=Hcompany/Holo-3.1-35B-A3B

Terminal-launched hosts inherit shell exports. GUI apps launched from the Dock or Finder usually need these values in the host’s MCP or ACP environment settings. For Claude Code, also confirm you installed HoloDesktop CLI from the workspace where you are using Claude Code:

cd /path/to/your/claude-code-workspace
holo install claude-code

Claude Code’s MCP CLI uses local scope by default, so the MCP server registration is associated with the workspace where the command ran.

Check runtime resolution

HoloDesktop CLI resolves hai-agent-runtime in this order:

hai-agent-runtime on PATH
managed install under ~/.holo/runtime/
download-on-first-run

Run:

holo doctor

The binary row shows which runtime path HoloDesktop CLI will use. If you are testing a local runtime build, put a deliberate hai-agent-runtime wrapper on PATH. Otherwise, let the CLI use the managed runtime.

Check logs

Runtime startup logs live under:

~/.holo/logs/

Per-run event logs live under:

~/.holo/runs/

To isolate one run, choose a temporary run directory:

holo run \
  --runs-dir /tmp/holo-runs \
  --max-steps 5 \
  "Open TextEdit and write the word test"

For timing output, add:

--profile

Use runtime logs for startup, model, port, permission, and binary-resolution failures. Use run logs when the runtime started but the task failed, timed out, or acted in the wrong place.

Understand run logs

Each run writes a JSONL event log under:

~/.holo/runs/<run-id>/events.jsonl

For a normal holo run, the run directory usually contains events.jsonl. Observation events inside that file can include the raw screenshot HoloDesktop CLI saw as a base64 JPEG, plus metadata such as viewport size, cursor position, and sometimes accessibility data. Treat run logs as sensitive: they may contain screenshots, task text, app content, and model reasoning.

Do not post events.jsonl, ~/.holo/runs/, or screenshots from a run publicly without review. They can include what the model saw on screen, including account names, local paths, messages, documents, and secrets.

Each line is one timestamped runtime event. The exact JSON shape is diagnostic and may change, so do not build production integrations against it. Use the sequence to find where a failed run got stuck.

Event kind	What it means	What to look for
`message_event`	The task or follow-up message reached the runtime	Confirms the runtime received the task string you expected
`observation_event`	The runtime captured or processed the visible desktop state	If this is missing or followed by permission-looking errors, check Screen Recording
`policy_event`	The model planned the next action	Look for the planned tool name and whether the action matches the task
`tool_result_event`	A desktop action finished or failed	Look for failed clicks, typing, app activation, or other tool errors
`permission_request`	The runtime needs user approval for an app or capability	Grant or deny in the UI, then retry if the runtime needs to restart
`permission_decision`	A permission request was granted or denied	Denied permissions explain missing screenshots, clicks, or typing
`error_event`	The runtime surfaced an error during the session	Read the error text, then check `~/.holo/logs/` for startup details
`answer_event`	The runtime produced the final response	Confirms the run reached an end-of-turn rather than timing out

Example event lines:

{"ts":"2026-06-15T12:00:00Z","event":{"kind":"message_event","text_content":"Open TextEdit and write test"}}
{"ts":"2026-06-15T12:00:01Z","event":{"kind":"observation_event","observation":{"kind":"computer","image":{"type":"base64","media_type":"image/jpeg","source":"..."}}}}
{"ts":"2026-06-15T12:00:03Z","event":{"kind":"policy_event","tool_reqs":[{"tool_name":"click_desktop"}]}}
{"ts":"2026-06-15T12:00:05Z","event":{"kind":"tool_result_event","tool_req":{"tool_name":"click_desktop"}}}
{"ts":"2026-06-15T12:00:06Z","event":{"kind":"answer_event","answer":"done"}}

Here is a shortened real log sketch for a run whose prompt was Open Calculator and compute 2+2:

message_event
  content: Open Calculator and compute 2+2

observation_event
  The runtime saw the desktop. Viewport: 1920x1243. Screenshot: embedded JPEG.

policy_event
  note: open Calculator with Spotlight
  tool: hotkey_desktop {"keys": ["cmd", "space"]}

tool_result
  hotkey_desktop completed

policy_event
  note: type Calculator into Spotlight
  tool: write_desktop {"content": "Calculator", "overwrite": true}

tool_result
  write_desktop completed

policy_event
  note: press Enter to open Calculator
  tool: hotkey_desktop {"keys": ["enter"]}

tool_result
  hotkey_desktop completed

observation_event
  Calculator is visible.

policy_event
  note: click the plus button
  tool: click_desktop {"element": "Orange plus (+) button"}

tool_result
  click_desktop completed

policy_event
  note: click the 2 button
  tool: click_desktop {"element": "Number 2 button"}

tool_result
  click_desktop completed

observation_event
  Calculator shows 2+2.

answer_event
  Final answer says the calculator shows 2+2 and clicking equals would display 4.

This run reached answer_event, but the event sequence shows the runtime never clicked =. That distinction matters: the runtime completed from the agent’s perspective, but the task was not fully done. Use the sequence to localize the failure:

Log pattern	Usually means
No `message_event`	The client did not create a session or wrote logs somewhere else
`message_event` but no `observation_event`	Runtime startup, screen capture, or permission problem
`observation_event` but no `policy_event`	Model backend did not respond, model request failed, or model was too slow
`policy_event` but no `tool_result_event`	Desktop tool execution failed or hung
Repeated `policy_event` / `tool_result_event` pairs	The agent is acting, but may be looping or stuck on the UI
`permission_request` followed by denied `permission_decision`	The run needs user approval before it can continue
`error_event` appears	The session failed inside the runtime; read the error and runtime log together
`answer_event` is present but task result is wrong	The run completed from the agent’s perspective; improve the task string or inspect earlier actions

For timing summaries, prefer:

holo run --profile "Open TextEdit and write the word test"

--profile reads the event log and prints per-step observe, model, tool, and total timings.

Check desktop permissions

A runtime that starts but cannot observe the screen or click is almost always a permissions problem. Grant permissions to the process that launches HoloDesktop CLI: for CLI runs that is usually your terminal; for MCP or ACP it may be the host app. The requirements are per-platform (macOS needs Screen Recording and Accessibility; Windows needs none; Linux needs an X11 session). See Desktop permissions for the full matrix. After granting on macOS, restart the launching process; grants do not apply to an already-running runtime.

Common fixes

Symptom	Likely cause	Try
`No HAI_API_KEY found`	Hosted mode is not signed in	`holo login`
Local endpoint works in terminal but not host	Host did not inherit env vars	Add env vars to host config or launch host from that shell
Claude Code cannot see HoloDesktop CLI	Installed in a different workspace	Re-run `holo install claude-code` from the active workspace
Runtime starts but cannot observe	Screen Recording missing	Grant permission and restart the runtime
Runtime observes but cannot click/type	Accessibility missing	Grant permission and restart the runtime
A host-launched run will not stop	Host did not propagate cancellation	Cancel from the host, or close the host’s stdio connection to HoloDesktop CLI
HoloDesktop CLI controls the wrong monitor	Target app is on a secondary display	Move the app to the primary display, mirror displays, or disconnect secondary monitors
`--base-url` run fails before contacting model	Runtime/config mismatch	Update to the fixed runtime/client version and retry
Task times out	Task is too broad or model is slow	Use a smaller task, `--max-steps`, or a faster model

What’s next

Use MCP if the failure only happens inside an agent host.

Getting Started

Integrations

How-to guides

Reference

Examples

Quick checklist

Start with doctor

Reproduce with the CLI

Stop a bad run first

Check model mode

Check host environment

Check runtime resolution

Check logs

Understand run logs

Check desktop permissions

Common fixes

What’s next

​Quick checklist

​Start with doctor

​Reproduce with the CLI

​Stop a bad run first

​Check model mode

​Check host environment

​Check runtime resolution

​Check logs

​Understand run logs

​Check desktop permissions

​Common fixes

​What’s next

Quick checklist

Start with doctor

Reproduce with the CLI

Stop a bad run first

Check model mode

Check host environment

Check runtime resolution

Check logs

Understand run logs

Check desktop permissions

Common fixes

What’s next