Skip to main content
You’ll have HoloDesktop CLI running a real task in a few minutes. On macOS and Windows, the installer sets up the holo command, a private Python toolchain, and the managed desktop runtime for you. You need an H Company account for hosted mode.
1

Install the CLI

Install the holo command, then verify it.
We currently support macOS and Windows. If you want support for another system, message us at support@hcompany.ai.
Open a new terminal after install, then check the command:
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:
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

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.

​
Develop from source

Use this path only if you are changing HoloDesktop CLI itself. You need Git, Python 3.12 or newer, and uv.
From a source checkout, prefix CLI examples with uv run, such as uv run holo doctor.

​
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.