> ## 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, in the cloud or on your desktop.
\~/projects
## Get started
### 1. Install
```bash theme={"system"}
pip install "hai-agents[cli]"
```
`holo` ships with the `hai-agents` package and also installs as `hai`. For an agent that drives this machine, add the `desktop` extra, or `browser` to drive [your Chrome](https://hub.hcompany.ai/agents-api/your-browser.md): `pip install "hai-agents[cli,desktop,browser]"`.
### 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`.
To use H agents from Claude Code, Cursor, or Codex, run [`holo mcp install`](https://hub.hcompany.ai/agents-api/coding-agents#local-server).
## 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](https://hub.hcompany.ai/holo-cli/reference.md#chat).
## Drive your desktop
```bash theme={"system"}
holo -a h/holo-desktop "Open TextEdit and write a short note saying the holo CLI is installed"
```
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 you stop it:
* **Kill switch:** press Esc twice quickly. Works even while Holo holds focus, once [permissions](#desktop-permissions) are granted.
* **Terminal:** Ctrl+C where you launched it, or `holo local stop` from any terminal.
* **MCP host:** cancel from your client. If the run keeps going, use `holo local stop`.
* **Limits:** `--max-steps` and `--max-time` bound a risky task up front.
`h/holo-desktop` 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. A run that drives this machine stops after 150 steps or 30 minutes by default.
Task-writing tips are in [Coding agents](https://hub.hcompany.ai/agents-api/coding-agents.md#write-a-good-task). To build your own desktop agent, start from [Your desktop](https://hub.hcompany.ai/agents-api/your-desktop.md).
### Models
Override the model for one run, for example with the faster `holo4-35b-a3b` from [Models](https://hub.hcompany.ai/models-api/overview.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.
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.
## Run the agent loop locally
| 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 |
`--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 go to H in every case, unless you [run the model yourself](#run-the-model-yourself).
```bash theme={"system"}
holo --local -a h/holo-desktop "Open TextEdit and write a short note"
```
The first run downloads the [runtime](https://hub.hcompany.ai/holo-cli/reference.md#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 a server you start with [Local inference](https://hub.hcompany.ai/agents-api/local-inference.md):
```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, as explained in [Local runtime](https://hub.hcompany.ai/agents-api/local-runtime.md#use-your-own-model-server).
## Security and privacy
An agent that drives this machine [takes control of your desktop](#drive-your-desktop). What leaves your machine depends on where the agent loop and the model run.
### What H receives
| Mode | Sent to H | Not uploaded |
| - | - | - |
| Agent loop in H's cloud (default) | The task, your [`~/.holo` files](#customize-every-run), and the session's steps, screenshots, and tool results. The session is kept like any other, with a [live view](https://hub.hcompany.ai/agents-api/observe-and-steer.md). | Files the agent does not open, and local logs |
| `--local`, hosted model | The agent lookup, and each model request: task, instructions, action history, screenshots | The session, tool results the model never sees, and local logs |
| `--local`, your model server on this machine | The agent lookup only. Your H API key never goes to your server | Everything else |
| `--local`, your model server elsewhere | The agent lookup only. That server gets the model requests | Everything else |
Cloud agents such as `h/web-surfer-flash` drive a browser on H's infrastructure in every mode, so they cannot use your own model server.
What the Models API keeps of each model request, and H's certifications, are in [Data retention](https://hub.hcompany.ai/models-api/overview.md#data-retention).
### What the agent can see
Anything on screen can end up in a screenshot: other apps and tabs, documents, chats, account names, file paths, and secrets. The terminal output and the runtime log under `~/.hai/agent-runtime/logs/` can contain the same things. They stay on your machine, but review them before you share them.
When a [coding agent](https://hub.hcompany.ai/agents-api/coding-agents.md#local-server) runs `holo`, the host decides when to call it and what task to send. The server asks the host to confirm with the user before an agent sends, deletes, pays, or changes settings, but the host still decides, so this is not a safety boundary. Check whether the host asks before tool calls, and whether its MCP config is global or per project. The data still goes where the mode above sends it.
### Before a sensitive run
1. Close unrelated windows, tabs, chats, and password managers.
2. Use `--local` with [your own model](#run-the-model-yourself) if the task must not reach H.
3. Use a separate browser profile for web apps, away from your personal cookies.
4. Keep the task narrow, so the agent opens fewer apps.
5. Rotate any credential that showed up in shared logs or screenshots.
## 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, as described in [Security and privacy](#security-and-privacy).
`~/.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//SKILL.md` holds your [skills](https://hub.hcompany.ai/agents-api/skills/overview.md), one folder each, in the format described in [Files](https://hub.hcompany.ai/holo-cli/reference.md#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.
```
## Reference
Commands, options, environment variables, files, and fixes for common errors are in [Reference](https://hub.hcompany.ai/holo-cli/reference.md).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.