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

> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# Use HoloDesktop CLI from an agent host

> Let Claude Code, Cursor, Codex, and other MCP hosts hand desktop work to HoloDesktop CLI, with a skill that teaches them when to.

export const Notice = ({kind = "note", title, children}) => {
  const kinds = {
    warning: {
      label: "User notice",
      icon: <>
          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
          <path d="M12 9v4" />
          <path d="M12 17h.01" />
        </>
    },
    gotcha: {
      label: "Gotcha",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    },
    note: {
      label: "Note",
      icon: <>
          <circle cx="12" cy="12" r="10" />
          <path d="M12 16v-4" />
          <path d="M12 8h.01" />
        </>
    }
  };
  const k = kinds[kind];
  return <div className="notice my-6 rounded-xl border border-zinc-200 bg-white p-5 dark:border-zinc-800 dark:bg-zinc-950">
      <div className={`${kind === "warning" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-red-400/80 dark:text-red-400/70" : kind === "gotcha" ? "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-amber-500/80 dark:text-amber-400/70" : "not-prose flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wide text-zinc-400 dark:text-zinc-500"}`}>
        <svg className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          {k.icon}
        </svg>
        {k.label}
      </div>
      {title && <div className="not-prose mt-2 text-base font-semibold text-zinc-900 dark:text-zinc-100">{title}</div>}
      <div className="notice-body mt-3 text-sm leading-6 text-zinc-700 dark:text-zinc-300">{children}</div>
    </div>;
};

Coding assistants and agent hosts can delegate desktop work to Holo over [MCP](https://modelcontextprotocol.io). `holo mcp` is a stdio MCP server with one tool, `holo_desktop`. Where the host loads skills, `holo install` also adds a `holo-desktop` skill: MCP tells the host how to reach Holo, and the skill tells it when to.

## Before you start

Run one task from a terminal, and sign in there: hosts launch the CLI non-interactively, so they cannot complete browser sign-in.

```bash theme={"system"}
holo login
holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
```

Running your own model server? Give the host `HAI_AGENT_RUNTIME_BASE_URL` and `HAI_AGENT_RUNTIME_MODEL` instead. See [Run the model yourself](/holo-desktop-cli/getting-started/quickstart#run-the-model-yourself).

## Install into a host

```bash theme={"system"}
holo install list      # supported hosts, and which are detected
holo install cursor    # one host
holo install           # every detected host
```

| Host ID | Host | Skill |
| - | - | - |
| `claude-code` | Claude Code | `~/.claude/skills/holo-desktop` |
| `claude-desktop` | Claude Desktop | |
| `codex` | Codex | `~/.agents/skills/holo-desktop` |
| `cursor` | Cursor | |
| `grok-build` | Grok Build | `~/.grok/skills/holo-desktop` |
| `opencode` | OpenCode | `~/.config/opencode/skills/holo-desktop` |
| `openclaw` | OpenClaw | `~/.openclaw/skills/holo-desktop` |
| `hermes` | Hermes | |
| `copilot` | GitHub Copilot CLI | |
| `antigravity` | Antigravity | |

`holo install` calls the host's own MCP CLI (Claude Code at user scope, so every project sees it) or merges an entry into its config file, keeping your other keys and saving the original as `<file>.bak`. It writes the absolute path to `holo`, so GUI hosts do not depend on your shell `PATH`. It also registers the double-`Esc` kill switch to start at login. Restart the host afterwards.

For file-backed hosts such as Cursor, the entry looks like this. Add the `env` block to use your own model server:

```json theme={"system"}
{
  "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": "holo4-35b-a3b"
      }
    }
  }
}
```

## What the host gets

```text theme={"system"}
holo_desktop(task: str) -> str
```

<Notice kind="gotcha" title="The tool call blocks until the task ends">
  `holo_desktop` is a blocking call, not a background job. It keeps observing, clicking, and typing until the task completes or hits its budget (150 steps or 30 minutes). One agent drives the desktop at a time, so parallel calls queue.
</Notice>

Holo does not see the host conversation, so each call must be self-contained: the app, workspace, account, person, and success condition.

```text theme={"system"}
# Good
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.
```

The skill teaches the host exactly this: hand off screen-bound work (native apps, system UI, the user's logged-in browser, 2FA prompts, UI checks), keep the rest, and write a self-contained task. A skill is guidance, not a safety boundary. For actions the user might regret, such as sending, deleting, paying, or changing settings, the host should confirm first or ask Holo to observe and report.

## Stop a run

Stopping the turn in the host may not stop the desktop run: some hosts do not send a cancellation. Press `Esc` twice, or run `holo stop` from any terminal.

## Check it worked

Restart the host, then ask:

```text theme={"system"}
Use HoloDesktop CLI to open TextEdit and write a short note saying it is connected. Return "done" when the note is visible.
```

If the host cannot find or start Holo:

* Run `holo install list`, then `holo install <host-id>` again.
* For Claude Code, check `claude mcp get holo`.
* Check that the host process sees `HAI_API_KEY`, or your model server settings.
* Check `~/.hai/agent-runtime/logs/` for runtime startup errors.

More in [Troubleshoot](/holo-desktop-cli/how-to/debug-failed-run). Worked example: [Fix a UI bug with Claude Code](/holo-desktop-cli/examples/claude-code-ui-qa).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.