Skip to main content
Run one safe desktop task to check that HoloDesktop CLI can start, reach a model backend, install the runtime, observe the screen, and act on the visible desktop.

​
Before you start

Complete Installation, then choose a hosted or local model. For hosted mode, check that login works: 
uv run holo whoami
On macOS, keep System Settings open. HoloDesktop CLI needs Screen Recording to observe your desktop and Accessibility to click and type.
Grant Screen Recording and Accessibility to the app that launches HoloDesktop CLI. For CLI runs that is usually your terminal; for MCP or ACP it may be the host app. Restart the launcher after granting permissions.
HoloDesktop CLI currently drives one visible screen: the primary display. Keep the target app on that screen. For important runs, disconnect or mirror extra displays. Multi-screen support is planned.
When you start a run, HoloDesktop CLI takes control of the visible desktop. It may open apps, switch focus, click, type, and observe whatever is on screen until the task completes, times out, or is stopped.To stop it, press Esc twice quickly, press Ctrl+C in the terminal or agent host that launched it, abort the host request, or run uv run holo stop from another terminal.

​
Run in hosted mode

uv run holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
For hosted mode, use API model IDs such as holo3-1-35b-a3b or holo3-122b-a10b when you need to override the default model.

​
Run in local mode

uv run holo run \
  --base-url http://localhost:8000/v1 \
  "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
Add --model Hcompany/Holo-3.1-35B-A3B if your local server requires a model ID.

​
What happens on first run

The first time HoloDesktop CLI runs a desktop task, it installs the computer-use agent runtime for you. The Python client in this checkout is the command-line wrapper. The runtime is the separate executable that observes the screen, plans actions, clicks, and types. Its binary is named hai-agent-runtime. If the CLI does not find hai-agent-runtime on PATH, it downloads the pinned runtime version and installs it under: 
~/.holo/runtime/
Most users do not need to manage this directory directly. On macOS, the first run may also ask for:
  • Screen Recording
  • Accessibility
Grant both permissions when prompted. If macOS grants the permission but the first task still fails, retry the command once. Permission grants can require the runtime to restart before they take effect.

​
Check it worked

The task worked if TextEdit opens and contains the requested note. HoloDesktop CLI also prints progress and a final answer in your terminal.
You are ready for host integrations when the CLI task completes, the requested note is visible, and the terminal prints a final answer.

​
Stop a run

If HoloDesktop CLI starts doing the wrong thing, press Esc twice quickly. For a normal interactive holo run, double-Esc sends a stop request to the active run. You can also stop a run from another terminal: 
uv run holo stop
Stopping is step-bounded: the CLI pauses and cancels the active run at the next safe point, so the current click, type, or app action may finish first. Use the force option only if the normal stop path does not respond: 
uv run holo stop --force
On macOS, double-Esc may ask for Input Monitoring permission. Grant it to the process that launches the listener, then retry.

​
Common first-run failures

The CLI asks you to sign in.
You are using hosted mode without a key. Run uv run holo login, complete browser sign-in, then retry the task. The local model server fails.
If you passed --base-url, verify the local server is running and OpenAI-compatible. The runtime cannot download.
Check your network connection. If you are testing a local runtime build, put a hai-agent-runtime executable or wrapper on PATH. HoloDesktop CLI can see the screen but cannot click or type. On macOS, check Accessibility permissions for the terminal or app that launched the CLI.

​
What’s next

Use the first run checklist if the run fails or the output is unclear.