Skip to main content
Use this checklist when a first HoloDesktop CLI run fails or behaves unexpectedly.

​
Checklist

CheckCommand or locationSuccess looks like
CLI is availableuv run holo --helpHelp prints without an import or command error
Hosted mode is readyuv run holo whoamiYour signed-in identity prints
Local mode is ready--base-url http://localhost:8000/v1The CLI reaches your local OpenAI-compatible server and does not require login
Runtime is available~/.holo/runtime/ or hai-agent-runtime on PATHFirst run downloads or resolves the runtime
Run logs are written~/.holo/runs/Per-run event logs appear after a task
Runtime logs are written~/.holo/logs/Runtime startup/failure logs appear when needed
macOS Screen Recording is grantedSystem SettingsThe CLI can observe the screen
macOS Accessibility is grantedSystem SettingsThe CLI can click and type
Stop worksDouble-Esc or uv run holo stopThe active run stops or reports interrupted
App is on the primary displayDisplay settings / desktop layoutThe CLI can see and control the app it needs

​
Check the CLI

From the checkout: 
uv run holo --help
If this fails, run uv sync again from the repo root.

​
Check model mode

For hosted mode: 
uv run holo whoami
If you are not signed in: 
uv run holo login
For local model mode, pass --base-url to holo run instead of signing in. For MCP or ACP local mode, make sure the host process can read: 
HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1
Terminal-launched hosts inherit shell exports. GUI apps launched from the Dock or Finder usually need the same value in the host’s MCP or ACP environment settings.

​
Check the runtime

HoloDesktop CLI resolves the runtime in this order:
  1. hai-agent-runtime on PATH
  2. managed install under ~/.holo/runtime/
  3. download-on-first-run
If the runtime download fails, retry on a network that can reach the runtime artifact. If you are testing a local runtime, put a hai-agent-runtime executable or wrapper on PATH.

​
Check macOS permissions

HoloDesktop CLI needs both:
  • Screen Recording, to observe the desktop;
  • Accessibility, to click and type.
Grant permissions to the app that launches HoloDesktop CLI, such as your terminal or agent host. If a permission prompt appears during the first run, grant it and retry the task once after the runtime restarts. For double-Esc stopping on macOS, grant Input Monitoring when prompted. Interactive CLI runs listen from the terminal process. MCP and ACP runs usually rely on the installed guard process instead.

​
Check display layout

HoloDesktop CLI currently observes and controls the primary display. If you use multiple monitors, move the target app to the primary screen before starting a run. For important or repeatable tests, disconnect or mirror secondary displays. Multi-screen support is planned.

​
Check stop control

During an interactive CLI run, press Esc twice quickly to request stop. From another terminal, use: 
uv run holo stop
If the run does not respond to the normal stop path, use: 
uv run holo stop --force
Normal stop is step-bounded, so an in-flight desktop action may finish before the run interrupts. --force kills the runtime process and should be reserved for stuck runs.

​
Check logs

Run artifacts and event logs are written under: 
~/.holo/runs/
Runtime startup logs are written under: 
~/.holo/logs/
Start with these logs when the runtime starts but the session fails.

​
What’s next

If this checklist passes, try Run your first task again. If the run still fails, use Debug a failed run. If the model setup is unclear, go back to Hosted or local models.