Create an environment

Create a reusable browser or desktop configuration in your catalog.

POST /api/v2/environments

Python

from hai_agents import Client

client = Client()

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

201

{
  "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
}

Behavior

Reference it by id (for example "environments": ["wide-browser"]) from any agent. Most agents define environments inline.

Request body

The body is a Browser spec (kind: "web", the default), documented below. A desktop on your own machine (kind: "desktop", Your desktop) 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).

id · string · required

Catalog identifier, with an optional single org/ namespace prefix. The h/ prefix is reserved for H’s catalog (rejected with 403). Immutable after creation.

kind · string · default: "web"

Environment type: web for a browser, desktop for a desktop.

host · string · default: "cloud"

Where the browser runs: cloud on H infrastructure, or user_device for Chrome on your own machine (Your browser).

start_url · string · default: "https://www.bing.com"

Initial URL to open.

headless · boolean · default: "false"

Run the browser without a visible window.

session_id · 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 holo local browser.

lazy · boolean · default: "false"

Start the browser on the agent’s first browser action instead of when the session starts. Skips the initial observation.

settle_s · number · default: "1.0"

Seconds the agent waits after each action, so the next observation shows the settled page. 0 to 10.

mode · object · default: "{\"type\": \"visual\"}"

How the agent perceives and drives the browser, as one of the modes. An object keyed by type (mode fields):

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

vault_id · string | null

ID of a vault 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.

browser_profile_id · string | null

ID of a browser profile 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.

use_default_browser_profile · boolean · default: "false"

Load your default browser profile 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.

persist_browser_profile · 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, the session starts read-only instead of failing.

network · object | null

Network settings for a newly provisioned browser, to route through a proxy. Ignored when session_id attaches to an existing browser. Set only one of managed_proxy and proxy_url.

managed_proxy · object | null

H provisions a proxy for browser egress. Credentials are resolved server-side and never appear in your requests.

pool · string · default: "residential"

residential or datacenter.

country · string | null

Two-letter ISO code.

sticky · boolean · default: "true"

Keep one exit IP for the session.

proxy_url · string | null

A bring-your-own HTTP/HTTPS/SOCKS proxy URL, with any credentials inline, for example http://user:pass@host:port.

Response

201 with the created environment object.

Python

from hai_agents import Client

client = Client()

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

201

{
  "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.