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

# Create an environment

> Create a reusable environment in your own catalog.

Creates a new custom environment in your catalog. Once created, reference it by `id` (e.g. `"environments": ["wide-browser"]`) from any agent. Most users define environments inline on the agent instead; use this endpoint to reuse one environment across several agents.

**Returns** `201` with the created [Environment](/computer-use-agents/environments/overview) object.

***

## Request body

The body is a [Browser](/computer-use-agents/browser/configuration) spec.

<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">
  Environment type. Currently only `web`. Defaults to `web`.
</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="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](/computer-use-agents/browser/configuration#modes) and [Mode fields](/computer-use-agents/browser/configuration#mode-fields).
</ParamField>

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

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

<ParamField body="use_default_browser_profile" type="boolean" default="false">
  Load your [default browser profile](/computer-use-agents/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](/computer-use-agents/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 the browser session. Set only one of:

  * `managed_proxy`: have H provision 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 for browser egress, with any credentials inline (e.g. `http://user:pass@host:port`).

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

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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={null}
  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={null}
  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={null}
{
  "id": "wide-browser",
  "kind": "web",
  "start_url": "https://www.google.com",
  "mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": false},
  "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 fails validation; common cases: invalid `id` shape, missing required field. |