> ## Documentation Index > Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt > Use this file to discover all available pages before exploring further. # Debug a failed run > Use doctor, logs, permissions, and model checks to debug a HoloDesktop CLI 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](/holo-desktop-cli/getting-started/quickstart#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 ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} holo whoami ``` If this fails, run: ```bash theme={null} holo login ``` For local mode, confirm the OpenAI-compatible endpoint is reachable: ```bash theme={null} 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: ```bash theme={null} HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1 ``` and sometimes: ```bash theme={null} 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: ```bash theme={null} 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: 1. `hai-agent-runtime` on `PATH` 2. managed install under `~/.holo/runtime/` 3. download-on-first-run Run: ```bash theme={null} 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: ```text theme={null} ~/.holo/logs/ ``` Per-run event logs live under: ```text theme={null} ~/.holo/runs/ ``` To isolate one run, choose a temporary run directory: ```bash theme={null} holo run \ --runs-dir /tmp/holo-runs \ --max-steps 5 \ "Open TextEdit and write the word test" ``` For timing output, add: ```bash theme={null} --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: ```text theme={null} ~/.holo/runs//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: ```json theme={null} {"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`: ```text theme={null} 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: ```bash theme={null} 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](/holo-desktop-cli/getting-started/quickstart#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](/holo-desktop-cli/integrations/use-mcp) if the failure only happens inside an agent host.