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

# Create an environment

> Create a reusable environment in your catalog: a cloud browser, your own browser, or your own desktop, with its settings.

Creates a custom environment in your catalog. Reference it by `id` (e.g. `"environments": ["wide-browser"]`) from any agent. Most agents define environments inline. Register one here to reuse it across agents.

**Returns** `201` with the created [environment object](/agents-api/environments/retrieve#response).

## Request body

The body is a [Browser](/agents-api/browser/configuration) spec (`kind: "web"`, the default), documented below. A desktop on your own machine (`kind: "desktop"`, see [Local control](/agents-api/local-control)) takes only `id`, `host` (required), `session_id`, `lazy`, `settle_s` (default `0.5`), and `screenshot_max_width` (up to `1920` pixels, `null` keeps the host default; screenshots are only shrunk, never enlarged).

<ParamField body="id" type="string" required>
  Catalog identifier, kebab-case with an optional single `org/` namespace prefix. The `h/` prefix is reserved for H's catalog (rejected with `403`). Immutable after creation.
</ParamField>

<ParamField body="kind" type="string" default="web">
  Environment type: `web` for a browser, `desktop` for a desktop.
</ParamField>

<ParamField body="host" type="string" default="cloud">
  Where the browser runs: `cloud` on H infrastructure, or `user_device` for Chrome on your own machine. See [Local control](/agents-api/local-control).
</ParamField>

<ParamField body="start_url" type="string" default="https://www.bing.com">
  Initial URL to open.
</ParamField>

<ParamField body="headless" type="boolean" default="false">
  Run the browser without a visible window.
</ParamField>

<ParamField body="session_id" type="string | null">
  Attach to an existing browser session by id instead of starting a new one. For a `user_device` browser, the Python SDK sets it for you, so set it yourself only to attach to one served with `hai local browser`.
</ParamField>

<ParamField body="lazy" type="boolean" default="false">
  Start the browser on the agent's first browser action instead of when the session starts. Skips the initial observation. See [Configuration](/agents-api/browser/configuration).
</ParamField>

<ParamField body="settle_s" type="number" default="1.0">
  Seconds the agent waits after each action, so the next observation shows the settled page. `0` to `10`.
</ParamField>

<ParamField body="mode" type="object" default="{&#x22;type&#x22;: &#x22;visual&#x22;}">
  How the agent perceives and drives the browser. An object keyed by `type`:

  * `visual` (default): `{"type": "visual", "width": 1200, "height": 1200, "markdown": false}`. Set `markdown: true` to include the page's text alongside the screenshot.
  * `text`: `{"type": "text", "chunk_size": 20000}`. Read-only paginated markdown, no screenshots.

  See [Modes](/agents-api/browser/configuration#modes) and [Mode fields](/agents-api/browser/configuration#mode-fields).
</ParamField>

<ParamField body="vault_id" type="string | null">
  Id of a [vault](/agents-api/vaults/overview) to bind, letting the agent sign in to sites with secrets resolved from it. Must belong to your organization. Cloud browsers only. Omit to run without secret access.
</ParamField>

<ParamField body="browser_profile_id" type="string | null">
  Id of a [browser profile](/agents-api/browser/profiles) to load, restoring saved cookies and storage so the agent starts already signed in. Must belong to your organization. Cloud browsers only. Omit to start with a fresh profile.
</ParamField>

<ParamField body="use_default_browser_profile" type="boolean" default="false">
  Load your [default browser profile](/agents-api/browser/profiles#default-profiles) instead of naming one, auto-creating an empty one on first use. Sessions save their final state back automatically (best-effort). Mutually exclusive with `browser_profile_id`.
</ParamField>

<ParamField body="persist_browser_profile" type="boolean" default="false">
  Save the session's final browser state back into the loaded profile when it ends. Requires `browser_profile_id` or `use_default_browser_profile`. Best-effort: if another session is already [persisting the profile](/agents-api/browser/profiles#persisting-state-back-into-the-profile), the session starts read-only instead of failing.
</ParamField>

<ParamField body="network" type="object | null">
  Network settings for a newly provisioned browser (ignored when `session_id` attaches to an existing one). Set only one of:

  * `managed_proxy`: H provisions a proxy for browser egress. An object with `pool` (`residential`, default, or `datacenter`), `country` (two-letter ISO code, optional), and `sticky` (keep one exit IP for the session, default `true`). Credentials are resolved server-side and never appear in your requests.
  * `proxy_url`: a bring-your-own HTTP/HTTPS/SOCKS proxy URL, with any credentials inline (e.g. `http://user:pass@host:port`).

  See [Proxy](/agents-api/browser/proxy).
</ParamField>

## Examples

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
    -H "Authorization: Bearer $HAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "wide-browser",
      "kind": "web",
      "start_url": "https://www.google.com",
      "mode": {"type": "visual", "width": 1920, "height": 1080}
    }'
  ```

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

  client = Client()

  environment = client.environments.create_environment(
      id="wide-browser",
      start_url="https://www.google.com",
      mode={"type": "visual", "width": 1920, "height": 1080},
  )
  print(environment.id)
  ```

  ```typescript TypeScript theme={"system"}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  const environment = await client.environments.createEnvironment({
    kind: "web",
    id: "wide-browser",
    startUrl: "https://www.google.com",
    mode: { type: "visual", width: 1920, height: 1080 },
  });
  console.log(environment.id);
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "id": "wide-browser",
  "kind": "web",
  "host": "cloud",
  "start_url": "https://www.google.com",
  "headless": false,
  "session_id": null,
  "mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": false},
  "lazy": false,
  "settle_s": 1.0,
  "vault_id": null,
  "browser_profile_id": null,
  "use_default_browser_profile": false,
  "persist_browser_profile": false,
  "network": null
}
```

## Errors

| Status | Cause |
| - | - |
| `403` | Attempted to use the reserved `h/` namespace. |
| `409` | An environment with this `id` already exists in your catalog. |
| `422` | Body failed validation. Common cases: invalid `id` shape, missing required field. |


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