Holo CLI

Run H agents from your terminal, in the cloud or on your desktop.

Get started

1. Install

   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: pip install "hai-agents[cli,desktop,browser]".

2. Sign in

   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

   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.

To use H agents from Claude Code, Cursor, or Codex, run holo mcp install.

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.

Drive your desktop

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 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. 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. To build your own desktop agent, start from Your desktop.

Models

Override the model for one run, for example with the faster holo4-35b-a3b from Models.

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. It works with any agent. Model calls go to H in every case, unless you run the model yourself.

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

The first run downloads the 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:

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.

Security and privacy

An agent that drives this machine takes control of 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, and the session’s steps, screenshots, and tool results. The session is kept like any other, with a live view.	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.

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 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 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. Edits apply to the next session. They go wherever the task text goes, as described in 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, in the format described in 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.

Reference

Commands, options, environment variables, files, and fixes for common errors are in Reference.