> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HoloDesktop CLI

> Run Holo on your own computer, from your terminal.

export const Journey = ({stages}) => <div className="not-prose mt-6">
    {stages.map(([title, links, blurb], i) => <div key={title} className="relative flex gap-5 pb-8 last:pb-0">
        {i < stages.length - 1 && <div className="absolute w-px bg-zinc-200 dark:bg-zinc-800" style={{
  left: 15,
  top: 32,
  bottom: 0
}} />}
        <div className="relative z-10 flex h-8 w-8 shrink-0 items-center justify-center rounded-full border border-zinc-300 bg-white text-sm font-semibold text-zinc-700 dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-200">
          {i + 1}
        </div>
        <div className="min-w-0 flex-1">
          <div className="pt-1 text-lg font-semibold text-zinc-900 dark:text-zinc-100">{title}</div>
          {blurb && <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">{blurb}</p>}
          <div className="mt-3 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
            {links.map(([label, href, icon]) => <a key={href} href={href} className="outlined card flex items-center gap-3 rounded-lg bg-white px-4 py-3 text-sm font-medium text-zinc-800 no-underline dark:bg-zinc-950 dark:text-zinc-200">
                <Icon icon={icon} size={15} color="currentColor" />
                {label}
              </a>)}
          </div>
        </div>
      </div>)}
  </div>;

export const YouTube = ({id, title}) => <iframe className="aspect-video w-full rounded-xl border-0" src={`https://www.youtube-nocookie.com/embed/${id}?rel=0&modestbranding=1`} title={title} loading="lazy" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen />;

<Frame>
  <YouTube id="iHfKP7tLewU" title="Introducing HoloDesktop CLI" />
</Frame>

## Four ways to run it

One runtime, four front doors. Pick the one that matches where the task comes from.

| Surface | Command                                          | When                                                                           |
| ------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
| CLI     | `holo run "task"`                                | One-shot tasks from your terminal                                              |
| MCP     | `holo install`, or `holo mcp` in the host config | Delegate from Claude Code, Cursor, Codex                                       |
| ACP     | `holo acp`                                       | Hermes, OpenClaw, Zed, other [ACP](https://agentclientprotocol.com) hosts      |
| A2A     | `holo serve`                                     | An [A2A](https://a2a-protocol.org) HTTP server on loopback for your own agents |

Inference is your call too: H's hosted Models API by default, or any OpenAI-compatible server on your own hardware with `--base-url`, in which case no screenshot, keystroke, or app content leaves your machine.

## Start here

Install, pick how you launch it, then tune it to your setup.

<Journey
  stages={[
["Get started", [
  ["Quickstart", "/holo-desktop-cli/getting-started/quickstart", "rocket"],
  ["Hosted or local models", "/holo-desktop-cli/getting-started/hosted-or-local-models", "server"],
  ["Desktop permissions", "/holo-desktop-cli/getting-started/quickstart#desktop-permissions", "shield-check"],
  ["Architecture", "/holo-desktop-cli/architecture", "diagram-project"],
  ["Security and privacy", "/holo-desktop-cli/security-and-privacy", "lock"],
], "Install, connect a model, and run your first task."],
["Use it", [
  ["From the terminal", "/holo-desktop-cli/integrations/use-from-cli", "terminal"],
  ["From Claude Code, Cursor, or Codex", "/holo-desktop-cli/integrations/agent-hosts", "plug"],
  ["As a skill", "/holo-desktop-cli/integrations/use-as-skill", "book-open"],
  ["From Python", "/holo-desktop-cli/how-to/embed-with-python", "code"],
], "One local runtime, launched from a terminal, an agent host, or your own code."],
["Customize and debug", [
  ["Customize", "/holo-desktop-cli/how-to/customize", "sliders"],
  ["Debug a failed run", "/holo-desktop-cli/how-to/debug-failed-run", "bug"],
  ["CLI reference", "/holo-desktop-cli/reference/cli", "terminal"],
  ["Environment variables", "/holo-desktop-cli/reference/environment-variables", "gear"],
  ["Paths and files", "/holo-desktop-cli/reference/paths-and-files", "folder"],
]],
["Learn from examples", [
  ["Fix a UI bug with Claude Code", "/holo-desktop-cli/examples/claude-code-ui-qa", "wrench"],
  ["Automate an expense report", "/holo-desktop-cli/examples/expense-report-automation", "receipt"],
]],
]}
/>

## Supported platforms

The `holo` client is pure Python and runs anywhere Python does. The `hai-agent-runtime` binary it drives is downloaded on first run where H publishes it, and bring-your-own elsewhere.

<CardGroup cols={2}>
  <Card title="macOS, Apple Silicon" icon="apple">
    Runtime downloaded on first run. Needs Screen Recording and Accessibility permissions.
  </Card>

  <Card title="Windows, x86_64 and ARM64" icon="windows">
    Runtime downloaded on first run. No extra permissions.
  </Card>

  <Card title="Linux, x86_64" icon="linux">
    Runtime downloaded on first run. Needs an X11 session. Wayland is not supported.
  </Card>

  <Card title="macOS, Intel" icon="apple">
    Bring your own runtime. Put `hai-agent-runtime` on `PATH`, or set a download URL.
  </Card>
</CardGroup>

On bring-your-own platforms, install the `holo` client normally, then put a `hai-agent-runtime` executable on `PATH`, or point `HAI_AGENT_RUNTIME_DOWNLOAD_URL` and `HAI_AGENT_RUNTIME_DOWNLOAD_SHA256` at a trusted build. The CLI checks `PATH` first, so your binary wins over the managed one. See [Runtime cache](/holo-desktop-cli/reference/paths-and-files#runtime-cache).

## What's next

Two things are coming, with no firm dates yet:

* **Background mode.** Today the agent drives the screen in front of you and shares your mouse and keyboard. Next, it binds to its own window so you keep using your machine while it works.
* **Native app.** The same agent as a desktop app beside your daily workflow, no terminal needed.

Have a request that isn't here? Send it to [support@hcompany.ai](mailto:support@hcompany.ai).