> ## 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 three 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), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). The `holo` CLI (`pip install "hai-agents[cli]"`) runs Agents API agents from a terminal, drives the user's own desktop with `-a h/holo-desktop`, and serves coding agents through `holo mcp`.
> 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: `holo`.
> 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.

# Holo CLI

> Run H agents from your terminal with the holo command: one-shot tasks, interactive sessions, an agent that drives your own desktop, and coding agents.

`holo` ships with the `hai-agents` package and also installs as `hai`.

| To | Run | Agent loop | Drives |
| - | - | - | - |
| Run one task on a cloud browser | `holo "task"` | H's cloud | A cloud browser |
| Let an agent drive this machine | `holo -a h/holo-desktop "task"` | H's cloud | This machine |
| Run the agent loop on this machine | `holo --local "task"` | This machine | A cloud browser |
| Keep both on this machine | `holo --local -a h/holo-desktop "task"` | This machine | This machine |

`holo` alone opens an [interactive session](#interactive-sessions). To use H agents from Claude Code, Cursor, or Codex, run [`holo mcp install`](https://hub.hcompany.ai/agents-api/coding-agents#local-server).

### 1. Install

```bash theme={"system"}
pip install "hai-agents[cli]"
```

For an agent that drives this machine, add the `workstation` extra: `pip install "hai-agents[cli,workstation]"`.

### 2. Sign in

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

This opens the H Platform in your browser and saves an API key. Scripts can set `HAI_API_KEY` instead.

### 3. Run a task

```bash theme={"system"}
holo "Open Hacker News and list the top 3 stories with their URLs."
```

This starts a [session](https://hub.hcompany.ai/agents-api/sessions/overview.md) on `h/web-surfer-flash`, prints each step, then the answer. Pick another agent with `--agent`, or change the default with `holo agents use h/web-surfer-pro`.

## Interactive sessions

`holo` alone opens a prompt. Each message continues the same session, so the agent keeps its browser and context. Press `Enter` to message the agent while it works, `Esc` to pause it, and `Ctrl+D` to leave. Type `/` for commands and `?` for keys. All keys: [Chat](#chat).

## Where it runs

The agent decides what it drives: a cloud browser, or [your browser](https://hub.hcompany.ai/agents-api/your-browser.md) or [desktop](https://hub.hcompany.ai/agents-api/your-desktop.md). `--local` decides where the agent loop runs, through the [local runtime](https://hub.hcompany.ai/agents-api/local-runtime.md). The table above shows each pair. Model calls go to H in every case, unless you [run the model yourself](#run-the-model-yourself).

## Drive your desktop

```bash theme={"system"}
holo -a h/holo-desktop "Open TextEdit and write a short note saying the holo CLI is installed"
```

User notice

Takes control of your desktop

While a task runs, the agent 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.

<dl />

`h/holo-desktop` uses your screen, mouse, keyboard, shell, and files. It drives the primary display, so keep the target app there. The first run on macOS may ask for [permissions](#desktop-permissions). One agent drives the desktop at a time. A second one waits up to 10 seconds, then fails.

To build your own desktop agent instead, see [Your desktop](https://hub.hcompany.ai/agents-api/your-desktop.md).

The agent only sees the task. Name the app, the account when it matters, the action, and what done looks like. See [Write a good task](https://hub.hcompany.ai/agents-api/coding-agents.md#write-a-good-task).

A run that drives this machine stops after 150 steps or 30 minutes by default.

[Introducing HoloDesktop CLI](https://www.youtube-nocookie.com/embed/iHfKP7tLewU?rel=0\&modestbranding=1)

### Stop a run

The notice above lists every way to stop. `holo local stop` stops every run on this machine, including runs a coding agent started.

### Models

Override the model for one run, for example with the faster `holo4-35b-a3b`. All IDs: [Models API](https://hub.hcompany.ai/models-api/quickstart.md#models).

```bash theme={"system"}
holo -a h/holo-desktop -o agent.model=holo4-35b-a3b "Open TextEdit and write a short note"
```

### Desktop permissions

Grant these to the app that starts `holo`: your terminal, or your coding agent.

**macOS**

In System Settings, Privacy & Security:

* **Screen Recording**, to see the screen.
* **Accessibility**, to click and type.
* **Input Monitoring**, for the `Esc` twice kill switch. Without it, use `holo local stop`.

Restart that app after granting. `holo doctor` shows missing Accessibility and Screen Recording grants.

**Windows**

No permission needed. To drive an app running as administrator, start your terminal as administrator.

**Linux**

No permission needed. Run in a normal desktop session so the agent can reach the display.

The `Esc` twice kill switch needs `pip install pynput` and an X11 session. Wayland has no global key listener, so use `holo local stop` there.

## Customize every run

`holo` adds two optional things from `~/.holo/` to every agent it runs, from the terminal and from [coding agents](https://hub.hcompany.ai/agents-api/coding-agents.md#local-server). Edits apply to the next session. They go wherever the task text goes: see [Security and privacy](https://hub.hcompany.ai/agents-api/cli/security.md).

`~/.holo/agents.md` holds standing instructions, added after the agent's own:

```text ~/.holo/agents.md theme={"system"}
My name is Alex. Reply in English.
Prefer keyboard shortcuts over mouse clicks.
```

`~/.holo/skills/<name>/SKILL.md` holds your [skills](https://hub.hcompany.ai/agents-api/skills/overview.md), one folder each. Format rules: [Files](#files).

```text ~/.holo/skills/file-an-expense/SKILL.md theme={"system"}
---
description: File an expense report in the internal portal from a receipt image.
---

1. Open the expense portal and click "New expense".
2. Upload the receipt, then fill amount, date, and category from it.
3. Stop before submitting and show the form.
```

## Run the agent loop locally

`--local` fetches the agent from H and runs it in the [local runtime](https://hub.hcompany.ai/agents-api/local-runtime.md). It works with any agent. Model calls and cloud environments, such as a cloud browser, still go to H.

```bash theme={"system"}
holo --local -a h/holo-desktop "Open TextEdit and write a short note"
```

The first run downloads the runtime. Supported platforms: [Runtime](#runtime).

### Run the model yourself

With `--local`, an agent that runs on this machine, such as `h/holo-desktop`, can send its model calls to your own server. Start a server with [Local inference](https://hub.hcompany.ai/models-api/local-inference.md), then:

```bash theme={"system"}
export HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1
export HAI_AGENT_RUNTIME_MODEL=holo4-35b-a3b
holo --local -a h/holo-desktop -o agent.model=holo4-35b-a3b "Open TextEdit and write a short note"
```

`HAI_AGENT_RUNTIME_MODEL` is your server's model name, and `agent.model` the Holo version you serve. See [Two model names](https://hub.hcompany.ai/agents-api/local-runtime.md#two-model-names).

For [coding agents](https://hub.hcompany.ai/agents-api/coding-agents.md#local-server), set the two variables in the host's MCP `env` block, and have the host pass `model` to `run_agent`.

## Reference

`holo --help` lists every command, and `holo <command> --help` its options.

### Commands

| Command | Purpose |
| - | - |
| `holo "task"`, `holo run "task"` | Run one task and print the answer. Follow-ups continue the session in a terminal |
| `holo`, `holo chat` | Start an interactive session. See [Chat](#chat) |
| `holo login` | Sign in in the browser, and save an API key to `~/.config/hai/.env`. Does nothing if a key is already available. See [Login](#login) |
| `holo logout` | Remove the saved API key. A key exported in your shell is unaffected |
| `holo whoami` | Print the endpoint and where the API key comes from |
| `holo doctor` | Diagnose login, platform access, the local runtime, local browser, desktop, and workstation control, and the macOS grants of the app running it. Read-only |
| `holo agents list`, `get`, `use` | Browse agents, and set the default one |
| `holo skills list`, `get` | Browse [platform skills](https://hub.hcompany.ai/agents-api/skills/overview.md) |
| `holo sessions list`, `get`, `status`, `events`, `watch` | Inspect sessions |
| `holo sessions send`, `cancel`, `share`, `unshare` | Steer and share sessions |
| `holo mcp` | Run the local MCP server. Hosts start it. See [Coding agents](https://hub.hcompany.ai/agents-api/coding-agents.md#local-server) |
| `holo mcp install [host]` | Add `holo mcp` to a host, or with `--remote` the [hosted MCP server](https://hub.hcompany.ai/agents-api/mcp.md). See [Install into a host](https://hub.hcompany.ai/agents-api/coding-agents.md#install-into-a-host) |
| `holo local stop` | Stop every run driving this machine, like the double-`Esc` kill switch |
| `holo local browser`, `desktop`, `workstation` | Serve this machine to a session started elsewhere. See [holo local](#holo-local) |

### Global options

Put these before the command, as in `holo --json sessions list`.

| Option | Purpose |
| - | - |
| `--api-key KEY` | API key. Defaults to `HAI_API_KEY` |
| `--base-url URL` | Agent Platform URL. Defaults to `HAI_API_BASE_URL`, else the EU platform |
| `--json` | Print machine-readable JSON |

### Run

```bash theme={"system"}
holo run "Open Hacker News and list the top 3 stories with their URLs."
```

| Option | Purpose |
| - | - |
| `--agent NAME`, `-a` | Agent to run. Defaults to `h/web-surfer-flash`, or the one set with `holo agents use`. `NAME:N` pins revision `N` |
| `--local` | Run the agent loop on this machine, through the [local runtime](https://hub.hcompany.ai/agents-api/local-runtime.md) |
| `--max-steps N` | Stop after at most `N` agent steps. Uncapped by default, or `150` for a run that drives this machine |
| `--max-time SECONDS` | Stop after a wall-clock timeout. Uncapped by default, or `1800` for a run that drives this machine |
| `--quiet`, `-q` | Print only the final answer |
| `--override PATH=VALUE`, `-o` | Per-run [override](https://hub.hcompany.ai/agents-api/sessions/overview.md#overrides), repeatable. `VALUE` is parsed as JSON, else a string |

### Chat

`holo chat`, or `holo` alone, takes `--agent` and `--local`.

| Key or command | Does |
| - | - |
| Type, then `Enter` | Message the agent while it works |
| `Esc` | Pause the agent. `Esc` again resumes |
| `/answer` | Make it answer now |
| `Ctrl+C` | Cancel the turn, or clear the input. Twice to leave |
| `Ctrl+D`, `/exit` | Leave |
| `Up`, `Down`, `Ctrl+R` | Browse and search previous messages |
| `Tab` or `→` | Accept the grey suggestion |
| `\` then `Enter` | New line |
| `/new [task]` | Start a new session |
| `/retry` | Run the first task again in a new session |
| `/resume [n]` | Continue a recent session |
| `/agent [name]` | Switch agent and save it as the default |
| `/live`, `/share` | Open the live view, or create a public link |
| `/status`, `/copy` | Show session and usage, or copy the last answer |

* A session stays open for 10 minutes after each answer.
* While an agent drives this machine, your typing goes to your apps, so the prompt only listens for `Esc` twice.
* With `--local`, `/resume`, `/live`, and `/share` are off, since they need a cloud session.

### Login

| Option | Does |
| - | - |
| `--force` | Sign in again and rotate the saved key |
| `--key` | Save a key from [platform.hcompany.ai/settings/api-keys](https://platform.hcompany.ai/settings/api-keys), read from a hidden prompt or from stdin |

### holo local

These commands serve this machine to a session started elsewhere, such as a registered agent or the web app. Each prints the session ID it serves: set it on the agent's `user_device` environment. See [Your browser](https://hub.hcompany.ai/agents-api/your-browser.md) and [Your desktop](https://hub.hcompany.ai/agents-api/your-desktop.md).

| Command | Serves | Install extra |
| - | - | - |
| `holo local browser` | Chrome on this machine | `browser` |
| `holo local desktop` | This machine's mouse, keyboard, and screen | `desktop` |
| `holo local workstation` | A shell on this machine, running as you, that drives its screen and a Chrome | `workstation` |

| Flag | Command | Default | Meaning |
| - | - | - | - |
| `--session-id` | All three | Generated | Session ID to serve |
| `--debug-port` | `browser` | `9222` | Chrome remote-debugging port to attach to |
| `--max-width` | `desktop` | `1920` | Cap screenshot width in pixels. `0` disables |
| `--max-height` | `desktop` | `0` | Cap screenshot height in pixels. `0` disables |
| `--image-format` | `desktop` | `jpeg` | `png`, `jpeg`, or `webp` |
| `--quality` | `desktop` | `85` | Encoding quality, 1 to 100, for `jpeg` and `webp` |
| `--workspace` | `workstation` | `~/hai/<session id>` | Folder the shell starts in |

`holo local desktop` downscales and recompresses screenshots before upload. The desktop environment's `screenshot_max_width` caps width again on the agent's side, so the smaller limit applies.

In an interactive terminal, `desktop` and `workstation` also stop on `Esc` twice. If the kill switch cannot arm, they say so: use `holo local stop`. Requirements: [Desktop permissions](#desktop-permissions).

### Environment variables

| Variable | Purpose |
| - | - |
| `HAI_API_KEY` | API key |
| `HAI_API_BASE_URL` | Agent Platform URL. Same as `--base-url` |
| `HAI_AGENT` | Default agent. Set by `holo agents use` |
| `HAI_AGENT_RUNTIME_BASE_URL` | With `--local`: your OpenAI-compatible model server, such as `http://localhost:8000/v1`. Your H API key is never sent to it |
| `HAI_AGENT_RUNTIME_MODEL` | With `--local`: the model name sent to that server, such as `holo4-35b-a3b` |
| `HAI_AGENT_RUNTIME_PORT` | Loopback port of the local runtime. Defaults to `18795` for hosted inference. Each self-hosted server and model gets its own port |
| `HAI_AGENT_RUNTIME_API_TOKEN` | Bearer token for the local runtime. Generated when unset |
| `HAI_AGENT_LOCAL_BINARY_PATH` | Run this `hai-agent-runtime` executable |
| `HAI_AGENT_LOCAL_CACHE_DIR` | Runtime cache. Defaults to `~/.hai/agent-runtime` |
| `HAI_AGENT_RUNTIME_DOWNLOAD_URL`, `HAI_AGENT_RUNTIME_DOWNLOAD_SHA256` | Download a trusted runtime build. Set both or neither |

`HAI_API_KEY` is read from, in order: `--api-key`, the process environment, then `~/.config/hai/.env`. `XDG_CONFIG_HOME`, when set, replaces `~/.config`.

### Files

Treat all of these as sensitive.

| Path | Purpose |
| - | - |
| `~/.config/hai/.env` | API key, default agent, and the endpoint `holo mcp install` saved |
| `~/.config/hai/stop` | Stop request written by `holo local stop` and the double-`Esc` kill switch. A run obeys only a stop filed after it started |
| `~/.config/hai/desktop.lock` | Held by the agent driving the desktop, so one runs at a time |
| `~/.holo/agents.md` | Standing instructions added to every run. See [Customize every run](#customize-every-run) |
| `~/.holo/skills/<name>/SKILL.md` | Your skills, added to every run |
| `~/.hai/agent-runtime/logs/hai-agent-runtime-<port>.log` | Local runtime startup and error log |
| `~/.hai/agent-runtime/state/` | Each runtime's owner-only token and what it infers against, so local clients share a runtime but never one serving another model |

`holo` sends `agents.md` and your skills as the `agent.instructions` and `agent.skills` [overrides](https://hub.hcompany.ai/agents-api/sessions/overview.md#overrides). Your own `-o` overrides win.

A skill's directory name is its name. `SKILL.md` needs YAML frontmatter with a `description`, which the agent matches tasks against. A file without one stops the run with an error naming it. Only `SKILL.md` is read. A skill with the same name as one of the agent's replaces it.

### Runtime

`--local` resolves `hai-agent-runtime` in this order:

1. `HAI_AGENT_LOCAL_BINARY_PATH`
2. `hai-agent-runtime` on `PATH`
3. The managed install under `~/.hai/agent-runtime/bin/<version>/`
4. A sha256-verified download of the pinned version, on first run

`holo doctor` shows which one it will use.

| Platform | Download |
| - | - |
| macOS, Apple Silicon | Yes |
| Windows, x86\_64 and ARM64 | Yes |
| Linux x86\_64 | Yes. Needs glibc 2.34+ (Ubuntu 22.04, Debian 12, RHEL 9) |
| Other platforms | No. Put your own `hai-agent-runtime` on `PATH` |

### Troubleshoot

Start with `holo doctor`. Fix the first failing row.

If a coding agent's run fails, try the smallest version in a terminal:

```bash theme={"system"}
holo -a h/holo-desktop --max-steps 5 "Open TextEdit and write the word test"
```

If that works, the problem is the host: check that `holo whoami` finds a saved key, and that the host's MCP `env` block has the variables you need.

The terminal prints each step. Hosts get the same steps as MCP log messages. `holo sessions events <session-id>` shows a cloud session's full history. With `--local`, the runtime logs to `~/.hai/agent-runtime/logs/`. Before sharing logs, see [What the agent can see](https://hub.hcompany.ai/agents-api/cli/security.md#what-the-agent-can-see).

| Symptom | Fix |
| - | - |
| `No API key found` | `holo login` |
| `API error 401` | The key is invalid: `holo login --force` |
| `Local workstation control requires extra deps` | `pip install "hai-agents[cli,workstation]"` |
| `another agent is driving this desktop` | Wait for it, or run `holo local stop` |
| `... needs YAML frontmatter with a description` | Fix or remove that skill in `~/.holo/skills/` |
| Works in the terminal, not from the host | Run `holo login --force` so the key is saved, and set env vars in the host's MCP config |
| Claude Code cannot see `holo` | `holo mcp install claude-code`, check `claude mcp get holo`, restart Claude Code |
| The agent cannot see the screen | Grant Screen Recording to the app that starts `holo`, then restart it |
| The agent sees but cannot click or type | Grant Accessibility, then restart the app |
| A run from a host will not stop | `Esc` twice, or `holo local stop` |
| The agent drives the wrong monitor | Move the app to the primary display |
| `the runtime at ... infers against ..., not ...` | Two inference settings share `HAI_AGENT_RUNTIME_PORT`. Unset it, or use one port each |
| `a runtime of unknown inference already listens there` | An older runtime holds the port. Stop it, or set `HAI_AGENT_RUNTIME_PORT` to a free port |
| The task times out | Make it smaller, or use a faster model |


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