> ## 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.
# Architecture
> How the HoloDesktop CLI Python client, the hai-agent-runtime, the hosted or local model backend, and the CLI, MCP, ACP, A2A, and Python surfaces fit together.
Think of HoloDesktop CLI as a thin client around a local computer-use agent runtime.
There are two main pieces:
* the open-source Python client, distributed as `holo-desktop-cli`;
* the computer-use agent runtime executable, `hai-agent-runtime`.
The client is the part you run from your terminal, MCP host, ACP host, A2A client, or Python code. The runtime observes the screen, plans actions, clicks and types, and streams events back.
## The same runtime behind every surface
The CLI, MCP server, ACP server, A2A server, and Python client all route work to the same local runtime. The surface changes how the agent is invoked. It does not create a separate kind of computer-use agent.
| Surface | Use it for |
| - | - |
| CLI | Run one foreground desktop task from a terminal or script. |
| MCP | Let Claude Code, Cursor, Codex, or another MCP host call HoloDesktop CLI as a tool. |
| ACP | Let an ACP-compatible host delegate desktop work to HoloDesktop CLI as a subagent. |
| A2A | Let your own agents reach HoloDesktop CLI over HTTP on loopback. |
| Python | Start sessions and stream events from application code. |
A [skill](/holo-desktop-cli/integrations/use-as-skill) is not a separate surface: it gives an MCP host reusable instructions on when to hand off to HoloDesktop CLI.
For commands and flags, use [CLI reference](/holo-desktop-cli/reference/cli). For host setup, use [Agent hosts](/holo-desktop-cli/integrations/agent-hosts).
## Runtime lifecycle
The Python client starts or attaches to `hai-agent-runtime` on loopback: if a healthy runtime is already listening on the target port it is reused, otherwise the client starts one. Both run on your machine.
| | Owns |
| - | - |
| Client | Installation, launch, host integration, user-facing commands |
| Runtime | Desktop observation and action |
Cache paths, logs, token files, and run directories are listed in [Paths and files](/holo-desktop-cli/reference/paths-and-files).
## Inference path
The runtime sends model inputs either to H's Models API (hosted mode) or to an OpenAI-compatible endpoint you provide (local mode). Runtime, desktop control, and diagnostics stay on your machine in both modes. See [Hosted or local models](/holo-desktop-cli/getting-started/hosted-or-local-models) for setup and [Security and privacy](/holo-desktop-cli/security-and-privacy) for what each mode sends.
## Desktop control
The agent operates desktop state, not source code or APIs. It observes what is visible, plans the next action, and uses desktop tools to click, type, scroll, and switch apps.
Foreground state matters. A CLI task can move focus and use the active desktop while it runs. Host integrations may make it feel like a tool call, but the underlying action is still desktop operation.
The agent observes and acts; it does not verify. Check results with code, not another model call. The [expense-report example](/holo-desktop-cli/examples/expense-report-automation#adapt-the-pattern) shows the pattern.
## User context
The client snapshots user context at run start and sends it to the runtime with the task. From `~/.holo/` it picks up:
* standing instructions (`agents.md`);
* memories and rules;
* installed skills.
These files shape behavior, so keep them specific and review them first when a run behaves unexpectedly. Exact paths are in [Paths and files](/holo-desktop-cli/reference/paths-and-files).
## Run artifacts
The runtime emits events as it works. Clients use those events to print progress, stream updates, and debug failures. The same stream is also persisted locally as run artifacts.
For event structure, use [Debug a failed run](/holo-desktop-cli/how-to/debug-failed-run). For storage and privacy, use [Paths and files](/holo-desktop-cli/reference/paths-and-files) and [Security and privacy](/holo-desktop-cli/security-and-privacy#local-artifacts).
## Next steps
Pick where the model runs.
What the runtime sees and what leaves your machine.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.