Use HoloDesktop CLI from an agent host

Coding assistants and agent hosts can delegate desktop work to HoloDesktop CLI. Three protocols are supported, all fronting the same local runtime:

Protocol	Command	The host sees	Can cancel mid-run	Use it with
MCP	`holo mcp` (stdio)	One tool, `holo_desktop`	No, the call blocks until the task ends	Claude Code, Cursor, Codex, Grok Build, OpenCode
ACP	`holo acp` (stdio)	A sub-agent	Yes	Hermes, OpenClaw, Zed, other ACP hosts
A2A	`holo serve` (HTTP on loopback)	An A2A agent	Yes	Your own agents and orchestrators

holo install also drops a skill where the host supports one, so the parent agent learns when to hand off to HoloDesktop CLI, not just how to reach it. All three are beta. Host implementations are still moving, especially around cancellation of long-running desktop calls.

Before you start

Run one task from the terminal to check that HoloDesktop CLI starts on this machine:

holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"

Hosts launch the CLI non-interactively, so they cannot complete browser login. For hosted mode, sign in first and restart the host afterwards:

holo login
holo whoami

For local mode, the host process needs HAI_AGENT_RUNTIME_BASE_URL and HAI_AGENT_RUNTIME_MODEL. See Local mode from hosts for where to put them, including GUI apps that do not inherit shell exports.

Connect over MCP

List the hosts HoloDesktop CLI can install itself into, and whether each is detected on your machine:

holo install list

Host ID	Host
`claude-code`	Claude Code
`claude-desktop`	Claude Desktop
`codex`	Codex
`cursor`	Cursor
`grok-build`	Grok Build
`opencode`	OpenCode
`openclaw`	OpenClaw
`hermes`	Hermes
`copilot`	GitHub Copilot CLI
`antigravity`	Antigravity

Install into one host, or into every detected host at once:

holo install cursor
holo install

holo install either calls the host’s own MCP CLI or updates its MCP config file. When possible it writes the absolute path to the holo executable, so GUI hosts do not depend on your shell PATH. Re-running it preserves extra keys such as env. Claude Code registers the server at local scope, tied to the workspace you run the command from:

cd /path/to/your/claude-code-workspace
holo install claude-code

Grok Build gets both the MCP server (in ~/.grok/config.toml) and the bundled skill (under ~/.grok/skills/holo-desktop). Check with grok mcp list and grok inspect. For file-backed hosts such as Cursor, the installed entry looks like this. Add an env block for local mode:

{
  "mcpServers": {
    "holo": {
      "type": "stdio",
      "command": "/absolute/path/to/holo",
      "args": ["mcp"],
      "env": {
        "HAI_AGENT_RUNTIME_BASE_URL": "http://localhost:8000/v1",
        "HAI_AGENT_RUNTIME_MODEL": "holo3-1-35b-a3b"
      }
    }
  }
}

What the host gets

The MCP server exposes one tool:

holo_desktop(task: str) -> str

Each call should be a self-contained desktop task. The CLI does not see the host conversation, so the host has to include the app, workspace, account, person, and success condition. Good task:

Open Slack in the Acme workspace and send a DM to Sarah Chen saying "on my way". Return "sent" after the message appears.

Too vague:

Tell Sarah.

Connect over ACP

ACP host configuration differs by host. Point it at a stdio command that runs the ACP server:

command: holo
args: ["acp"]

From a source checkout, run it through uv instead:

command: uv
args: ["run", "holo", "acp"]

HoloDesktop CLI starts the desktop runtime locally and creates a desktop session for each task the host sends. ACP hosts can cancel an in-flight task, which is the main reason to pick it over MCP.

Connect over A2A

For agents you build yourself, run HoloDesktop CLI as an A2A server:

export HOLO_AUTH_TOKEN=$(openssl rand -hex 24)
holo serve

It listens on 127.0.0.1:18794 (change with --port), requires Authorization: Bearer $HOLO_AUTH_TOKEN on every request, and maps each A2A contextId to one desktop session, so a multi-turn conversation in your agent stays one session here. Pass --base-url and --model exactly as you would to holo run to use a local model.

Stop a run

The host owns the conversation, so cancel the tool call or sub-agent session from the host. HoloDesktop CLI cancels the active runtime session when it receives the cancellation or when the stdio connection closes. holo stop from any terminal, or Esc twice, also works: in headless surfaces the double-Esc is watched by holo guard, which holo install registers with the OS. See Stop a run. Avoid holo stop --force here. Hosts spawn their runtime once at startup, so a force-kill leaves the host process alive but pointing at a dead runtime, and every later task fails until you restart the host.

Check it worked

Restart the host after installation if it was already open. Then ask it to do a small, safe desktop task:

Open TextEdit and write a short note saying HoloDesktop CLI is connected. Return "done" when the note is visible.

If the host cannot find or start HoloDesktop CLI:

run holo install list and confirm the host ID, then re-run holo install <host-id>;
check that hosted mode has HAI_API_KEY, or local mode has HAI_AGENT_RUNTIME_BASE_URL, available to the host process;
for a source checkout, check that the command path points at the checkout where uv sync succeeded;
check ~/.holo/logs/ for runtime startup errors.

Get started

Integrations

How-to guides

Reference

Examples

Use HoloDesktop CLI from an agent host

Before you start

Connect over MCP

What the host gets

Connect over ACP

Connect over A2A

Stop a run

Check it worked

Next steps

Use as a skill

Debug a failed run

​Before you start

​Connect over MCP

​What the host gets

​Connect over ACP

​Connect over A2A

​Stop a run

​Check it worked

​Next steps

Use as a skill

Debug a failed run

Before you start

Connect over MCP

What the host gets

Connect over ACP

Connect over A2A

Stop a run

Check it worked

Next steps