Skip to main content
Use ACP when your host supports Agent Client Protocol sub-agents and should delegate desktop work to HoloDesktop CLI over stdio.
ACP support is beta. Use it with hosts that already understand ACP sub-agents, and expect host setup details to change.
When an ACP host delegates to HoloDesktop CLI, it delegates control of the visible desktop. The CLI may open apps, switch focus, click, type, and observe whatever is on screen until the task completes, times out, or is cancelled.
The host starts: 
uv run holo acp
HoloDesktop CLI starts the desktop runtime locally and creates desktop sessions as the host sends tasks.

​
Before you start

Check HoloDesktop CLI from the CLI first: 
uv run holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
For hosted mode, sign in from a terminal before starting the ACP host: 
uv run holo login
uv run holo whoami
For local mode, start your OpenAI-compatible server and make sure the host process can read your local model settings: 
export HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1
Set HAI_AGENT_RUNTIME_MODEL too if your local server requires a model ID, for example Hcompany/Holo-3.1-35B-A3B. That export works for terminal-launched hosts. GUI apps launched from the Dock or Finder usually do not inherit shell exports, so configure the host environment directly if it supports that, or start the host from a shell that already has the variables set.
ACP hosts are non-interactive stdio processes. Sign in before hosted-mode startup, and put local-mode environment variables somewhere the host process can actually read them.

​
Configure your host

ACP host configuration differs by host. Use a stdio command that runs the HoloDesktop CLI ACP server from the checkout: 
command: uv
args: ["run", "holo", "acp"]
If your host expects the holo executable directly and the checkout environment is already active, use: 
command: holo
args: ["acp"]

​
Stop an ACP run

For ACP, the host owns the sub-agent session and HoloDesktop CLI runs as a stdio process. Keep both stop paths available:
  • press Esc twice quickly if the guard is installed and running;
  • run uv run holo stop from a terminal if you need a host-independent stop request.
uv run holo stop
holo install can install the guard so double-Esc works for host-launched runs. On macOS, grant Input Monitoring to the guard when prompted; a listener inside the ACP process may not receive key events because macOS attributes the permission to the launching GUI app. Normal stop is step-bounded: the CLI pauses and cancels the active run at the next safe point. If the run is stuck and does not respond, use uv run holo stop --force, then restart the host if its ACP session is still blocked.

​
Check it worked

Ask the host to delegate a small desktop task to HoloDesktop CLI. Keep the task specific and self-contained: 
Open TextEdit and write a short note saying HoloDesktop CLI is connected through ACP. Return "done" when the note is visible.
If the host fails during startup, check:
  • hosted mode has HAI_API_KEY available;
  • local mode has HAI_AGENT_RUNTIME_BASE_URL available to the host process;
  • the command path points at the same checkout where uv sync succeeded;
  • runtime logs under ~/.holo/logs/.

​
ACP or MCP?

Use MCP when your host expects tools. Use ACP when your host expects sub-agents. Both surfaces start the same local desktop runtime; the difference is how the host talks to HoloDesktop CLI.

​
What’s next

Use MCP if your host supports MCP but not ACP.