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

> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# HoloDesktop CLI quickstart

> Install HoloDesktop CLI on macOS, Windows, or Linux, sign in or point it at a local model, run a first desktop task, and stop it.

export const DesktopControlWarning = () => {
  const Key = ({children}) => <kbd className="rounded border border-zinc-300 bg-zinc-100 px-1.5 py-0.5 font-mono text-xs font-medium text-zinc-800 dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-100">
      {children}
    </kbd>;
  const Code = ({children}) => <code className="rounded bg-zinc-100 px-1.5 py-0.5 font-mono text-xs text-zinc-800 dark:bg-zinc-800 dark:text-zinc-100">
      {children}
    </code>;
  const rows = [["Kill switch", <><Key>Esc</Key> <Key>Esc</Key> quickly. Works even while Holo holds focus.</>], ["Terminal", <><Key>Ctrl</Key>+<Key>C</Key> where you launched it, or <Code>holo stop</Code> from any terminal.</>], ["Host", <>Cancel from your MCP or ACP client.</>], ["Limits", <><Code>--max-steps</Code> and <Code>--max-time-s</Code> bound a risky task up front.</>]];
  return <div className="not-prose my-6 grid gap-6 rounded-xl border border-zinc-200 bg-white p-5 md:grid-cols-2 dark:border-zinc-800 dark:bg-zinc-950">
      <div>
        <div className="flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-red-400/80 dark:text-red-400/70">
          <svg className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" /><path d="M12 9v4" /><path d="M12 17h.01" /></svg>
          User notice
        </div>
        <div className="mt-2 text-base font-semibold text-zinc-900 dark:text-zinc-100">Takes control of your desktop</div>
        <p className="mt-4 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
          While a task runs, HoloDesktop CLI can open apps, switch focus, click, type, and read whatever is on screen. It keeps going until the task finishes, times out, or is cancelled.
        </p>
      </div>
      <dl className="divide-y divide-zinc-100 text-sm dark:divide-zinc-800">
        {rows.map(([k, v]) => <div key={k} className="flex gap-4 py-2 first:pt-0 last:pb-0">
            <dt className="w-24 shrink-0 text-zinc-500 dark:text-zinc-400">{k}</dt>
            <dd className="leading-6 text-zinc-800 dark:text-zinc-200">{v}</dd>
          </div>)}
      </dl>
    </div>;
};

<DesktopControlWarning />

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

<Steps titleSize="h3">
  <Step id="install" title="Install the CLI">
    Install the `holo` command, then verify it.

    <Tabs>
      <Tab title="macOS">
        ```bash theme={"system"}
        curl -fsSL https://install.hcompany.ai/install.sh | bash
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={"system"}
        irm https://install.hcompany.ai/install.ps1 | iex
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={"system"}
        curl -fsSL https://install.hcompany.ai/install.sh | bash
        ```
      </Tab>
    </Tabs>

    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](/holo-desktop-cli/introduction#supported-platforms).

    Open a new terminal after install, then check the command:

    ```bash theme={"system"}
    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`.
  </Step>

  <Step id="connect-a-model" title="Connect a model">
    Hosted mode is the default. Sign in once, then confirm the key is available:

    ```bash theme={"system"}
    holo login
    holo whoami
    ```

    To run a model yourself instead, bring up a local OpenAI-compatible server and pass `--base-url`. See [Hosted or local models](/holo-desktop-cli/getting-started/hosted-or-local-models#local-mode).
  </Step>

  <Step id="run-your-first-task" title="Run your first task">
    <Tabs>
      <Tab title="Hosted">
        ```bash theme={"system"}
        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.
      </Tab>

      <Tab title="Local">
        ```bash theme={"system"}
        holo run \
          --base-url http://localhost:8000/v1 \
          "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
        ```

        Add `--model holo3-1-35b-a3b` if your server requires a model ID. For vLLM it must match `--served-model-name`.
      </Tab>
    </Tabs>

    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](#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.
  </Step>

  <Step id="watch-and-stop" title="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](#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](/holo-desktop-cli/how-to/debug-failed-run).
  </Step>
</Steps>

## 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:

```bash theme={"system"}
holo run "Open Calendar, show today's events, and report each event with its time and title. Do not create or edit anything."
```

Too vague:

```bash theme={"system"}
holo run "What's on today?"
```

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](/holo-desktop-cli/reference/cli#run).

## Stop a run

| Method | When |
| - | - |
| `Esc` twice quickly | Anytime, even while Holo holds focus. Global kill switch; on macOS it needs Input Monitoring permission |
| `Ctrl+C` | You can reach the launching terminal |
| `holo stop` | From any other terminal, or for runs started by an MCP, ACP, or A2A host |
| `holo stop --force` | The runtime itself is wedged. Kills it outright |

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.

<Tabs>
  <Tab title="macOS">
    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.
  </Tab>

  <Tab title="Windows">
    No extra permission is required. Some elevated apps only accept input from an elevated process, so to drive them, start your terminal "as administrator".
  </Tab>

  <Tab title="Linux">
    Requires an X11 session; Wayland is not supported by the input backend. The first run downloads the managed Linux x86\_64 runtime automatically.
  </Tab>
</Tabs>

## Develop from source

Use this path only if you are changing HoloDesktop CLI itself. You need [Git](https://git-scm.com/), Python 3.12 or newer, and [`uv`](https://docs.astral.sh/uv/).

```bash theme={"system"}
git clone https://github.com/hcompai/holo-desktop-cli
cd holo-desktop-cli
make setup
uv run holo --help
```

From a source checkout, prefix CLI examples with `uv run`, such as `uv run holo doctor`.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Agent hosts" icon="plug" href="/holo-desktop-cli/integrations/agent-hosts">
    Call HoloDesktop CLI from Claude Code, Cursor, Codex, or an ACP or A2A host.
  </Card>

  <Card title="Examples" icon="flask" href="/holo-desktop-cli/examples/index">
    Complete workflows: a Claude Code UI-bug fix and a CLI expense report.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/holo-desktop-cli/architecture">
    How the client, runtime, model backend, and host surfaces fit together.
  </Card>

  <Card title="Debug a failed run" icon="bug" href="/holo-desktop-cli/how-to/debug-failed-run">
    Use doctor, logs, permissions, and model checks to localize a failure.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.