> ## 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 three 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), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). The `holo` CLI (`pip install "hai-agents[cli]"`) runs Agents API agents from a terminal, drives the user's own desktop with `-a h/holo-desktop`, and serves coding agents through `holo mcp`.
> 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: `holo`.
> 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.

# Your desktop

> Let an agent drive the real screen, mouse, and keyboard of your own machine: native apps, files, and multi-window flows.

Runs on macOS, Windows, and Linux. Python only: the SDK or the `holo` CLI. The environment is `{"kind": "desktop", "host": "user_device"}`.

This page builds your own desktop agent. For a ready-made one, `holo -a h/holo-desktop "task"` runs `h/holo-desktop`, which also gets a shell running as you and a Chrome (a `workstation` environment). See [Drive your desktop](https://hub.hcompany.ai/agents-api/cli.md#drive-your-desktop).

The agent acts on your real machine

It can move the mouse, type, read anything on screen, run shell commands, and read or write files. Prefer a dedicated machine over your primary one.

Stop a run at any time: [cancel the session](https://hub.hcompany.ai/agents-api/sessions/cancel.md) with `holo sessions cancel <session-id>`, or run `holo local stop` in any terminal to stop every local session on this machine. In an interactive terminal, `holo local desktop` also stops on Esc twice. See [Stop a run](https://hub.hcompany.ai/agents-api/cli.md#stop-a-run) for what the kill switch needs.

## Run a session

```bash Install theme={"system"}
pip install "hai-agents[cli,desktop]"
```

Create an agent whose environment sets `host` to `user_device`, then run a session with it. In Python there is nothing else to set up. From the CLI, serve your desktop and point the agent at the `session_id` it prints (the CLI example uses the agent the Python example creates). All flags: [`holo local`](https://hub.hcompany.ai/agents-api/cli#holo-local).

```python Python theme={"system"}
from hai_agents import Client

client = Client()

agent = client.agents.create_agent(
    name="local-desktop",
    description="Drives the desktop on my own machine.",
    environments=[{"id": "my-laptop", "kind": "desktop", "host": "user_device"}],
)

result = client.run_session(
    agent=agent,
    messages="Open Notes and write a short summary of today's standup",
)
print(result.status, result.answer)
```

```bash CLI theme={"system"}
# Serve the desktop and leave it running; it prints the session_id it serves.
holo local desktop

# In another terminal, route the agent's desktop environment here.
holo run "Open Notes and write a short summary of today's standup" \
  --agent local-desktop \
  -o 'agent.environments[kind=desktop].session_id=<printed id>'
```

The program running the agent (your terminal, or the app that launches Python) needs [desktop permissions](https://hub.hcompany.ai/agents-api/cli.md#desktop-permissions). Your first session triggers the prompts and stops with an error until you grant them. Run the program in a normal desktop session so it can reach the display.

## Fields

| Field | Default | Description |
| - | - | - |
| `id` | required | Catalog identifier. |
| `kind` | | `"desktop"`. |
| `host` | | `"user_device"`. |
| `session_id` | `null` | Command channel of this desktop. The Python SDK sets it. Set it yourself only to attach to `holo local desktop`. |
| `lazy` | `false` | Connect on the agent's first desktop action, skipping the initial screenshot. |
| `settle_s` | `0.5` | Seconds the agent waits after each action. `0` to `10`. |
| `screenshot_max_width` | `null` | Maximum screenshot width in pixels, `1` to `1920`. `null` uses the host default. Never upscales. |

## Behavior and limits

When a session starts, the SDK opens a connection inside your Python process. It receives the agent's actions, carries them out on your desktop, and ties the session to this machine. [Observe and steer](https://hub.hcompany.ai/agents-api/observe-and-steer.md), [changes](https://hub.hcompany.ai/agents-api/sessions/changes.md), and [Agent View](https://hub.hcompany.ai/agents-api/observe-and-steer.md) work as for a cloud run.

* **One at a time.** A Python process drives one local desktop at a time. A new session on it takes it over and cancels the earlier session. Another process that tries to drive the same desktop waits up to 10 seconds, then fails with `DesktopBusyError`.
* **Tied to your process.** The connection closes when your Python process exits, and the sessions it served are cancelled. If the connection drops mid-session, the session is cancelled too.
* **Screenshots.** `holo local desktop` downscales and recompresses screenshots before upload. The environment's `screenshot_max_width` caps width again on the agent's side, so the smaller limit applies.

### Auto-connect scope

| You start the session with | Connection |
| - | - |
| An agent spec or object passed to `run_session`, `start_session`, or `create_session` | The SDK connects your machine for you. |
| A registered agent referenced by name, or from the web app or another machine | Serve the desktop with `holo local desktop`, then set the printed `session_id` on the `user_device` environment (see the CLI example above). |
| `HAI_AUTO_BRIDGE=0` set | Auto-connect is off. Serve the desktop yourself, as above. |


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