Skip to main content
The installer sets up the holo command, a private Python toolchain, and the managed desktop runtime. You need an H account for hosted mode.
1

Install the CLI

Install the holo command, then verify it.
The managed runtime supports macOS on Apple Silicon, Linux on x86_64, and Windows on x86_64 or ARM64. The Windows installer detects the architecture automatically. Other platforms: see Supported platforms.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 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.
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 it early, press Esc twice. See Stop a run.Per-run event logs are written under ~/.holo/runs/, runtime startup logs under ~/.holo/logs/. If the run failed or the output was unclear, see Debug a failed run.

​
Write good task strings

The agent only sees the task string you pass to holo run. Include the app, the account or workspace when it matters, the action to take, and what success looks like. Good:
Too vague:
Bound the run with --max-steps or --max-time-s, and pass --model when the backend needs a specific model ID. All options are in the CLI reference.

​
Stop a run

The first three are step-bounded: the action already in flight finishes, then the run pauses and cancels. Only --force is instant, and it leaves any headless host (holo mcp, holo acp, holo serve) pointing at a dead runtime until you restart the host. For headless surfaces the double-Esc is watched by holo guard, which holo install sets up for you. Bound risky tasks ahead of time with --max-steps or --max-time-s.

​
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

Agent hosts

Call HoloDesktop CLI from Claude Code, Cursor, Codex, or an ACP or A2A host.

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.