Skip to main content
You’ll have HoloDesktop CLI running a real task in a few minutes. You need Python 3.12 or newer (plus Git and uv to install from source), and an H Company account for hosted mode.
1

Install the CLI

Install the holo command, then verify it.
pip install holo-desktop-cli

holo --help
You should see subcommands such as run, mcp, acp, install, login, whoami, doctor, and serve. If holo is not found, reopen your shell so the freshly installed command is on PATH.
2

Connect a model

Hosted mode is the default. Sign in once, then confirm the key is available:
holo login
holo whoami
To run a model yourself instead, bring up a local OpenAI-compatible server and pass --base-url. See Run a local model server and Hosted or local models.
3

Run your first task

holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
Add --model holo3-1-35b-a3b to override the default hosted model.
The first run downloads the agent runtime for you (sha256-verified, into ~/.holo/runtime/). On macOS, it may prompt for Screen Recording and Accessibility; grant both and retry. See Desktop permissions below for the per-platform requirements. The CLI drives one screen, the primary display, so keep the target app there and mirror or disconnect extra displays for important runs.
HoloDesktop CLI takes control of the visible desktop while a task runs. It can open apps, switch focus, click, type, and read whatever is on screen until the task finishes, times out, or is cancelled.To stop a run, press Esc twice quickly: a global kill switch that works even while Holo holds focus and you cannot tab back to the terminal. You can also press Ctrl+C in the launching terminal, run holo stop from any terminal, or cancel from your MCP or ACP host. Bound risky tasks with --max-steps or --max-time-s.
4

Watch and stop

The task prints progress and a final answer in your terminal. It worked if TextEdit opens and contains the requested note.To stop a run, press Esc twice quickly. This is a global kill switch, so it works even while Holo has focus and you cannot tab back to the terminal. You can also press Ctrl+C in the launching terminal, or run holo stop from any other terminal. Bound longer tasks with --max-steps or --max-time-s.Per-run event logs are written under ~/.holo/runs/. If the run failed or the output was unclear, see Debug a failed run.

​
Desktop permissions

To observe and control the screen, the runtime needs OS-level permission on some platforms. Grant these to the app that launches the CLI, usually your terminal, or your MCP or ACP host.
Under System Settings → Privacy & Security, grant the launching app:
  • Screen Recording, so the runtime can see the desktop;
  • Accessibility, so it can click and type;
  • Input Monitoring, so the double-Esc kill switch can stop a run. Without it, use holo stop instead.
Restart the launching app after granting a permission. Grants do not apply to an already-running process. The first run prompts for these automatically.

​
Next steps

Integrations

Call HoloDesktop CLI from the terminal, an MCP or ACP host, or as a skill.

Examples

Complete workflows: a Claude Code UI-bug fix and a CLI expense report.

Architecture

How the client, runtime, model backend, and host surfaces fit together.

Debug a failed run

Use doctor, logs, permissions, and model checks to localize a failure.