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

# Run the agent loop on your machine

> Run the agent loop on your machine with Client.local(), on H's hosted model or your own Holo4 server.

`Client.local()` gives you the same [sessions](https://hub.hcompany.ai/agents-api/sessions/overview.md) API as the cloud. Only model calls go to H, plus any cloud browser you use. With [your own model server](#use-your-own-model-server) and your own browser or desktop, nothing does. Sessions start instantly, and each action runs next to the agent, with no network round trip. From the terminal, use [`holo --local`](https://hub.hcompany.ai/agents-api/cli#run-the-agent-loop-locally).

Where the agent loop runs is independent of what it drives: a cloud browser, [your browser](https://hub.hcompany.ai/agents-api/your-browser.md), or [your desktop](https://hub.hcompany.ai/agents-api/your-desktop.md).

### 1. Install the SDK

Add the driver for your environment: `browser` or `desktop`.

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

### 2. Sign in

Model calls go to H with your API key. Sign in once, or set `HAI_API_KEY`:

```bash CLI theme={"system"}
holo login
```

### 3. Run a session

Pass the agent spec inline:

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

agent = {
    "name": "local-web",
    "description": "Drives Chrome on this machine.",
    "environments": [{"id": "browser", "kind": "web", "host": "user_device"}],
}

with Client.local() as client:
    result = client.run_session(agent=agent, messages="Open example.com and tell me the page heading.")
    print(result.status, result.answer)
```

The first run downloads the local runtime, about 60 MB. Later runs reuse it.

## Cloud vs local

| | `Client()` | `Client.local()` |
| - | - | - |
| Environments | Cloud and local | Cloud and local, inline only. Cloud environments need H's hosted model, not [your own model server](#use-your-own-model-server) |
| Web search | Yes | No |
| Agents | Registered or inline | Inline, without `subagents` |
| API | The full Agents API | Sessions |
| Platforms | Any | macOS (Apple silicon), Windows (x64, ARM64), Linux (x64). See [Runtime](https://hub.hcompany.ai/agents-api/cli.md#runtime) |

## Use your own model server

Run Holo4 on hardware you control. Your H API key is never sent to it, so you can skip [Sign in](#sign-in) and the `cli` extra, but cloud environments cannot run. The model server can run on any machine you can reach.

```text theme={"system"}
your code ──► Client.local() ──► local runtime ──► your model server
                                      └──► your browser or desktop
```

### 1. Serve Holo4

Start a Holo4 server with [Local inference](https://hub.hcompany.ai/models-api/local-inference.md#start-a-server): vLLM on an NVIDIA GPU (base URL `http://localhost:8000/v1`) or llama.cpp on a Mac (`http://localhost:8080/v1`).

### 2. Point the runtime at it

Use the `agent` from [Run a session](#run-a-session), with its `model` set:

```python Python theme={"system"}
from hai_agents_local.runtime import Inference

agent["model"] = "holo4-35b-a3b"
inference = Inference.self_hosted("http://localhost:8000/v1", model="holo4-35b-a3b")

with Client.local(inference=inference) as client:
    result = client.run_session(agent=agent, messages="Open example.com and tell me the page heading.")
    print(result.status, result.answer)
```

With llama.cpp, use `http://localhost:8080/v1`. Without `inference`, `Client.local()` reads `HAI_AGENT_RUNTIME_BASE_URL` and `HAI_AGENT_RUNTIME_MODEL` instead.

### Two model names

| Field | Value |
| - | - |
| Agent `model` | The Holo version you serve: `holo4-35b-a3b`, `holo4-27b`, or `holo3-1-35b-a3b`. Sets the prompt format. |
| `Inference.self_hosted(model=...)` | Your server's model name. |

Always set the agent's model

Without it, the agent uses the Holo3.1 format.

### GPUs on another machine

No API key is sent to your server, so keep it private. Use an SSH tunnel and keep `http://localhost:8000/v1`:

```bash SSH tunnel theme={"system"}
ssh -N -L 8000:localhost:8000 you@gpu-host
```

## Troubleshooting

| Error | Fix |
| - | - |
| `No health endpoint at http://.../health` | The base URL must end in `/v1`, and the server must answer `GET /health`. |
| `inference selection cannot reconfigure an existing runtime` | Close the other client, or pass `local_options={"port": 18796}`. |
| `Unknown model '...'` | Use an agent `model` from [Two model names](#two-model-names). |


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