Skip to main content
“ACP” here means the Agent Client Protocol (client to agent) that editors and CLIs use to drive a sub-agent, not the older Agent Communication Protocol that merged into A2A.
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 read whatever is on screen until the task finishes, times out, or is cancelled.
The host starts:
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:
For hosted mode, sign in from a terminal before starting the ACP host:
For local mode, start your OpenAI-compatible server and make sure the host process can read your local model settings:
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. Because 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 a source checkout, run it through uv instead:

​
Stop an ACP run

For ACP, the host owns the sub-agent session and HoloDesktop CLI runs as a stdio process. Cancel the session from the host; HoloDesktop CLI cancels the active runtime session on host cancellation or when the stdio connection closes. Bound longer tasks with the runtime’s step and time budgets.

​
Check it worked

Ask the host to delegate a small desktop task to HoloDesktop CLI. Keep the task specific and self-contained:
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.