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

# Quickstart

> Install HoloDesktop CLI, connect a model, and run your first desktop task in minutes.

You'll have HoloDesktop CLI running a real task in a few minutes. On macOS, Windows, and Linux, 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.

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

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

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

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

    <Note>
      Managed runtime downloads support macOS on Apple Silicon and Windows or Linux on x86\_64.
    </Note>

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

    ```bash theme={null}
    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={null}
    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](/holo-desktop-cli/how-to/run-a-local-model-server) and [Hosted or local models](/holo-desktop-cli/getting-started/hosted-or-local-models).
  </Step>

  <Step id="run-your-first-task" title="Run your first task">
    <Tabs>
      <Tab title="Hosted">
        ```bash theme={null}
        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={null}
        holo run \
          --base-url http://localhost:8000/v1 \
          "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
        ```

        Add `--model Hcompany/Holo-3.1-35B-A3B` if your server requires a model ID.
      </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.

    <Danger>
      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`.
    </Danger>
  </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 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](/holo-desktop-cli/how-to/debug-failed-run).
  </Step>
</Steps>

## 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={null}
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="Integrations" icon="plug" href="/holo-desktop-cli/integrations/use-from-cli">
    Call HoloDesktop CLI from the terminal, an MCP or ACP host, or as a skill.
  </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>