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

# Route the browser through a proxy

> Egress the browser through an H-managed proxy or one you operate.

export const ProxyRouting = () => {
  const stroke = {
    fill: "none",
    stroke: "currentColor",
    strokeWidth: 1.75,
    strokeLinecap: "round",
    strokeLinejoin: "round"
  };
  const S = c => ({
    className: c,
    ...stroke
  });
  const icons = {
    globe: c => <svg viewBox="0 0 24 24" {...S(c)}><circle cx="12" cy="12" r="10" /><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /><path d="M2 12h20" /></svg>,
    route: c => <svg viewBox="0 0 24 24" {...S(c)}><circle cx="6" cy="19" r="3" /><path d="M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" /><circle cx="18" cy="5" r="3" /></svg>,
    site: c => <svg viewBox="0 0 24 24" {...S(c)}><rect x="2" y="4" width="20" height="16" rx="2" /><path d="M2 8h20M6 4v4M10 4v4" /></svg>
  };
  const Card = ({icon, title, sub, children}) => <div className="flex shrink-0 flex-col self-center rounded-xl border border-zinc-200 bg-white p-5 dark:border-zinc-800 dark:bg-zinc-950">
      <div className="flex items-center gap-2.5">
        <span className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-zinc-100 text-zinc-700 dark:bg-zinc-800 dark:text-zinc-200">{icon("h-5 w-5")}</span>
        <div>
          <div className="whitespace-nowrap text-base font-semibold leading-6 text-zinc-900 dark:text-zinc-100">{title}</div>
          <div className="whitespace-nowrap text-sm text-zinc-500 dark:text-zinc-400">{sub}</div>
        </div>
      </div>
      {children}
    </div>;
  const Arrow = ({top}) => <div className="flex min-w-[72px] flex-1 flex-col items-stretch justify-center gap-1 px-3 text-center text-xs leading-4 text-zinc-500 dark:text-zinc-400">
      <span className="whitespace-nowrap">{top || "\u00a0"}</span>
      <div className="flex items-center text-zinc-400 dark:text-zinc-600">
        <span className="h-px flex-1 bg-current" />
        <svg className="-ml-px h-3 w-2 shrink-0" viewBox="0 0 8 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><path d="M1 1.5 6 6l-5 4.5" /></svg>
      </div>
    </div>;
  const Chip = ({children}) => <span className="whitespace-nowrap rounded-md bg-zinc-100 px-2 py-0.5 font-mono text-xs text-zinc-600 dark:bg-zinc-800 dark:text-zinc-300">{children}</span>;
  const Option = ({title, chip, children}) => <div className="flex items-center justify-between gap-4 rounded-lg border border-zinc-200 px-3.5 py-2.5 dark:border-zinc-800">
      <div>
        <div className="text-sm font-medium text-zinc-900 dark:text-zinc-100">{title}</div>
        <div className="whitespace-nowrap text-xs text-zinc-500 dark:text-zinc-400">{children}</div>
      </div>
      <Chip>{chip}</Chip>
    </div>;
  return <div className="not-prose my-8 overflow-x-auto">
      <div className="flex min-w-[640px] items-stretch">
        <Card icon={icons.globe} title="Cloud browser" sub="in a session">
          <div className="mt-4 text-sm text-zinc-600 dark:text-zinc-400">All traffic exits<br />via the proxy</div>
        </Card>

        <Arrow />

        <Card icon={icons.route} title="Proxy" sub="pick one">
          <div className="mt-4 flex flex-col gap-2">
            <Option title="Managed" chip="managed_proxy">H provisions it, you pick pool and country</Option>
            <Option title="Bring your own" chip="proxy_url">You operate it</Option>
          </div>
        </Card>

        <Arrow top="exit IP" />

        <Card icon={icons.site} title="Target site" sub="sees the proxy, not H">
          <div className="mt-4 text-sm text-zinc-600 dark:text-zinc-400">Unblocks IP-blocked<br />and geofenced sites</div>
        </Card>
      </div>
    </div>;
};

<ProxyRouting />

Route the browser's egress through a proxy when the target site blocks datacenter IPs or geofences by region, or when a run needs traffic from a specific network. The [browser environment](/agents-api/browser/configuration)'s `network` field supports two options:

* **Managed proxy** (`network.managed_proxy`): H provisions a proxy for the session. You pick the pool, country, and stickiness. The platform handles the provider and credentials.
* **Bring your own** (`network.proxy_url`): route through a proxy you operate, credentials inline.

The two are mutually exclusive. Set only one. Either applies when a cloud browser session is provisioned. A [local browser](/agents-api/browser/local-control) uses your machine's own network.

## Managed proxy

Ask H to provision the proxy by setting `network.managed_proxy`. The request carries intent only. Credentials are resolved server-side and never appear in your requests, session data, or logs.

| Field                           | Type           | Default         | Description                                                                                                                                                                                            |
| ------------------------------- | -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `network.managed_proxy.pool`    | string         | `"residential"` | IP pool to egress from: `residential` (real-ISP addresses, best for sites that block datacenter ranges) or `datacenter`. Requesting a pool that is not available in your environment fails with `400`. |
| `network.managed_proxy.country` | string \| null | `null`          | Two-letter ISO 3166-1 code (like `"US"`) to egress from a specific country. Omit for any location. Invalid codes fail with `422`.                                                                      |
| `network.managed_proxy.sticky`  | boolean        | `true`          | Keep the same exit IP for the whole session. Applies to residential pools. Datacenter endpoints manage rotation themselves.                                                                            |

Create a catalog browser environment that egresses from a US residential IP:

<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": "us-browser",
      "kind": "web",
      "network": {"managed_proxy": {"pool": "residential", "country": "US"}}
    }'
  ```

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

  client = Client()

  environment = client.environments.create_environment(
      id="us-browser",
      kind="web",
      network=BrowserNetwork(
          managed_proxy=ManagedProxySelection(pool="residential", country="US"),
      ),
  )
  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: "us-browser",
    network: { managedProxy: { pool: "residential", country: "US" } },
  });
  console.log(environment.id);
  ```
</CodeGroup>

## Bring your own proxy

Route through a proxy you operate by setting `network.proxy_url`.

| Field               | Type           | Default | Description                                                                                                                                                                       |
| ------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network.proxy_url` | string \| null | `null`  | Bring-your-own proxy URL for browser egress, with any credentials inline: `http://user:pass@host:port`. HTTP, HTTPS, and SOCKS schemes are accepted. Treat the value as a secret. |

Create a catalog browser environment that routes through your proxy:

<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": "proxy-browser",
      "kind": "web",
      "network": {"proxy_url": "http://user:pass@proxy.example.com:8080"}
    }'
  ```

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

  client = Client()

  environment = client.environments.create_environment(
      id="proxy-browser",
      kind="web",
      network=BrowserNetwork(proxy_url="http://user:pass@proxy.example.com:8080"),
  )
  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: "proxy-browser",
    network: { proxyUrl: "http://user:pass@proxy.example.com:8080" },
  });
  console.log(environment.id);
  ```
</CodeGroup>

## Next steps

<Card title="Browser configuration" icon="window" href="/agents-api/browser/configuration" horizontal>
  The rest of the browser environment: fields, modes, and actions.
</Card>