Holo CLI

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. To use H agents from Claude Code, Cursor, or Codex, run holo mcp install.

Install

pip install "hai-agents[cli]"

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

Run a task

holo "Open Hacker News and list the top 3 stories with their URLs."

This starts a session 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.

Where it runs

The agent decides what it drives: a cloud browser, or your browser or desktop. --local decides where the agent loop runs, through the local runtime. The table above shows each pair. Model calls go to H in every case, unless you run the model yourself.

Drive your desktop

holo -a h/holo-desktop "Open TextEdit and write a short note saying the holo CLI is installed"

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. 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. 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. A run that drives this machine stops after 150 steps or 30 minutes by default.

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.

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
Windows
Linux

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.

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. Edits apply to the next session. They go wherever the task text goes: see Security and privacy. ~/.holo/agents.md holds standing instructions, added after the agent’s own:

~/.holo/agents.md

My name is Alex. Reply in English.
Prefer keyboard shortcuts over mouse clicks.

~/.holo/skills/<name>/SKILL.md holds your skills, one folder each. Format rules: Files.

~/.holo/skills/file-an-expense/SKILL.md

---
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. It works with any agent. Model calls and cloud environments, such as a cloud browser, still go to H.

holo --local -a h/holo-desktop "Open TextEdit and write a short note"

The first run downloads the runtime. Supported platforms: 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, then:

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. For coding agents, 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
`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
`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
`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
`holo mcp install [host]`	Add `holo mcp` to a host, or with `--remote` the hosted MCP server. See 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

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

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
`--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, 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.

Option	Does
`--force`	Sign in again and rotate the saved key
`--key`	Save a key from 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 and Your desktop.

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.

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
`~/.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. 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:

HAI_AGENT_LOCAL_BINARY_PATH
hai-agent-runtime on PATH
The managed install under ~/.hai/agent-runtime/bin/<version>/
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:

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.

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

Build an agent

Environments

Run sessions

Tools and integrations

Production

Install

Run a task

Interactive sessions

Where it runs

Drive your desktop

Stop a run

Models

Desktop permissions

Customize every run

Run the agent loop locally

Run the model yourself

Reference

Commands

Global options

Run

Chat

holo local

Environment variables

Files

Runtime

Troubleshoot

Install

Sign in

Run a task

​Interactive sessions

​Where it runs

​Drive your desktop

​Stop a run

​Models

​Desktop permissions

​Customize every run

​Run the agent loop locally

​Run the model yourself

​Reference

​Commands

​Global options

​Run

​Chat

​Login

​holo local

​Environment variables

​Files

​Runtime

​Troubleshoot

Interactive sessions

Where it runs

Drive your desktop

Stop a run

Models

Desktop permissions

Customize every run

Run the agent loop locally

Run the model yourself

Reference

Commands

Global options

Run

Chat

Login

holo local

Environment variables

Files

Runtime

Troubleshoot