> ## 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 screen, mouse, and keyboard of your machine.

## Run a session

The agent acts on your real machine. It can move the mouse, type, and read anything on screen. With [`shell: true`](#fields) it also runs shell commands and reads or writes files. Prefer a dedicated machine over your primary one.

[Stop it](https://hub.hcompany.ai/holo-cli/introduction.md#drive-your-desktop) with Esc twice, or `holo local stop` in any terminal, which stops every session driving this machine.

For a pre-built agent, [`holo -a h/holo-desktop "task"`](https://hub.hcompany.ai/holo-cli/introduction#drive-your-desktop) runs `h/holo-desktop`.

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

It works on macOS, Windows, and Linux, from the Python SDK and the CLI. Create an agent with a `desktop` environment, then run a session with it. In Python there is nothing else to set up. From the CLI, serve your desktop with [`holo local desktop`](https://hub.hcompany.ai/holo-cli/reference#holo-local) and point the agent at the `session_id` it prints (the CLI example uses the agent the Python example creates).

```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>'
```

```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"}],
)

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

The program running the agent (your terminal, or the app that launches Python) needs [desktop permissions](https://hub.hcompany.ai/holo-cli/introduction.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"`. |
| `shell` | `false` | `true` drives the machine from a shell: commands, files, and the screen and browser through command-line tools. `false` drives the screen with mouse and keyboard actions and a screenshot after each step. `true` is in preview: without access, requests fail with `403` `environment_not_public`. |
| `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. |
| `screenshot_max_width` | `null` | Maximum screenshot width in pixels, `1` to `1920`. `null` uses `1920`. 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. [Watch and steer](https://hub.hcompany.ai/agents-api/observe-and-steer.md) and [changes](https://hub.hcompany.ai/agents-api/sessions/changes.md) work as in the cloud.

* A Python process drives one 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, then fails](https://hub.hcompany.ai/holo-cli/introduction.md#drive-your-desktop) with `DesktopBusyError`.
* 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.
* [`holo local desktop`](https://hub.hcompany.ai/holo-cli/reference#holo-local) shrinks screenshots before upload.

### 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 H Platform or another machine | Serve the desktop with `holo local desktop`, then set the printed `session_id` on the `desktop` 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.