> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use HoloDesktop CLI as an ACP sub-agent

> Delegate desktop tasks to HoloDesktop CLI from an Agent Client Protocol host over stdio.

"ACP" here means the [Agent Client Protocol](https://agentclientprotocol.com) (client to agent) that editors and CLIs use to drive a sub-agent, not the older Agent Communication Protocol that merged into A2A.

<Note>
  ACP support is beta. Use it with hosts that already understand ACP sub-agents, and expect host setup details to change.
</Note>

<Danger>
  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.
</Danger>

The host starts:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
holo login
holo whoami
```

For local mode, start your OpenAI-compatible server and make sure the host process can read your local model settings:

```bash theme={null}
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. 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:

```text theme={null}
command: holo
args: ["acp"]
```

From a source checkout, run it through `uv` instead:

```text theme={null}
command: uv
args: ["run", "holo", "acp"]
```

## 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:

```text theme={null}
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](/holo-desktop-cli/integrations/use-mcp) if your host supports MCP but not ACP.