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

> What each Holo CLI command and setting does, and how to fix common errors.

## Commands

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

| 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 [chat](#chat) session |
| `holo login` | [Sign in](#login) in the browser, and save an API key to `~/.config/hai/.env`. Does nothing if a key is already available |
| `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 and desktop 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 for [coding agents](https://hub.hcompany.ai/agents-api/coding-agents.md#local-server). Hosts start it |
| `holo mcp install [host]` | [Add `holo mcp` to a host](https://hub.hcompany.ai/agents-api/coding-agents#install-into-a-host), or with `--remote` the [hosted MCP server](https://hub.hcompany.ai/agents-api/mcp.md) |
| `holo local stop` | Stop every run driving this machine, like the double-`Esc` kill switch |
| `holo local browser`, `desktop` | Serve this machine to a cloud agent loop, with [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

Serves this machine to a cloud agent loop. Not `--local`.

Use these commands for 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, as in [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` |

| Flag | Command | Default | Meaning |
| - | - | - | - |
| `--session-id` | Both | 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` |

`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, `holo local desktop` also stops on `Esc` twice, with the same [desktop permissions](https://hub.hcompany.ai/holo-cli/introduction.md#desktop-permissions). If the kill switch cannot arm, it says so: use `holo local stop`.

## 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](https://hub.hcompany.ai/holo-cli/introduction.md#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/`. Logs can hold anything that was on screen, so read [What the agent can see](https://hub.hcompany.ai/holo-cli/introduction.md#what-the-agent-can-see) before you share them.

| Symptom | Fix |
| - | - |
| `No API key found` | `holo login` |
| `API error 401` | The key is invalid: `holo login --force` |
| `Local desktop control requires hai-drivers>=0.1.2` | `pip install "hai-agents[cli,desktop]"` |
| `Local browser control requires extra deps` | `pip install "hai-agents[cli,browser]"` |
| `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.