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

# Run agents on your own machine

> Run the agent on your own machine with Client.local(): private, no startup wait, and faster tool calls, with the same sessions API as the cloud.

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>;
};

With local mode, the agent itself runs on **your own machine**. `Client.local()` returns a client with the same [sessions](/agents-api/sessions/overview) API as the cloud.

## Why local mode

* **Private.** The agent and its tools run on your machine; only model calls go to H. With [your own model server](#bring-your-own-model), nothing leaves it.
* **No startup wait.** No cloud agent to start: a session begins working right away.
* **Faster tool calls.** Each click, keystroke, and screenshot runs next to the agent, with no round trip through H's cloud.

With [local browser](/agents-api/browser/local-control) or [desktop control](/agents-api/desktop/local-control), only the browser or desktop is yours and the agent runs on H's platform. In local mode, the agent runs on your machine too.

<Notice kind="note" title="Python, macOS and Windows">
  Local mode ships in the `hai-agents` Python SDK, version 1.2.1 or later. It runs on macOS on Apple silicon and Windows on x64.
</Notice>

<Steps titleSize="h3">
  <Step id="install" title="Install the SDK">
    Install the SDK with the driver for the environment your agent uses: `browser` for a local browser, `desktop` for a local desktop.

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

  <Step id="sign-in" title="Sign in">
    Model calls go to H with your API key. Sign in once, or set `HAI_API_KEY`:

    ```bash CLI theme={"system"}
    hai login
    ```
  </Step>

  <Step id="run-a-session" title="Run a session">
    Pass the agent spec inline. This one drives Chrome on your machine:

    ```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.
  </Step>
</Steps>

<Notice kind="warning" title="Runs on your machine">
  A local browser or desktop gives the agent your logins, your files, and your screen. Read the warnings on [local browser control](/agents-api/browser/local-control) and [local desktop control](/agents-api/desktop/local-control) before you run one.
</Notice>

## Limits

| | `Client()` | `Client.local()` |
| - | - | - |
| Environments | Cloud and local | Local browser (`{"kind": "web", "host": "user_device"}`) and local desktop (`{"kind": "desktop", "host": "user_device"}`) |
| Web search | Yes | No |
| Agents | Registered or inline | Inline, without `subagents` |
| API | The full Agents API | Sessions |

## Bring your own model

Point local mode at any OpenAI-compatible server, such as Holo4 served with [vLLM or llama.cpp](/models-api/local-inference). Your H API key is never sent to it.

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

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.")
```

## Next steps

<CardGroup cols={2}>
  <Card title="Drive your own browser" icon="window" href="/agents-api/browser/local-control">
    The Chrome a local browser drives, and how to bring your own.
  </Card>

  <Card title="Local inference" icon="server" href="/models-api/local-inference">
    Serve Holo4 on your own hardware.
  </Card>

  <Card title="Custom tools" icon="screwdriver-wrench" href="/agents-api/custom-tools">
    Give the agent functions from your own code.
  </Card>

  <Card title="Observe & steer" icon="eye" href="/agents-api/observe-and-steer">
    Watch a run, redirect it mid-task, and read the answer.
  </Card>
</CardGroup>


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