> ## 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 Chip = ({children}) => <span className="rounded-md bg-zinc-100 px-2 py-0.5 font-mono text-[11px] text-zinc-600 dark:bg-zinc-800 dark:text-zinc-300">
      {children}
    </span>;
  const ArrowRight = () => <svg className="mx-3 h-4 w-8 shrink-0 self-center text-zinc-400 dark:text-zinc-500" viewBox="0 0 32 16" fill="none" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" strokeLinejoin="round"><path d="M1 8h27" /><path d="M23 3l6 5-6 5" /></svg>;
  return <div className="not-prose my-6 overflow-x-auto">
      <div className="flex items-center justify-center">
        <div className="flex w-[180px] shrink-0 flex-col self-center rounded-xl border border-transparent bg-zinc-900 p-4 dark:bg-zinc-100">
          <div className="flex items-center gap-2 text-[13.5px] font-semibold text-white dark:text-zinc-900">
            <svg className="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><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>
            <span>Browser</span>
          </div>
          <div className="mt-1 text-[11.5px] leading-4 text-zinc-400 dark:text-zinc-500">running in a session</div>
          <div className="mt-3 text-[11px] leading-4 text-zinc-400 dark:text-zinc-500">all traffic leaves through the proxy you set</div>
        </div>

        <ArrowRight />

        <div className="flex w-[240px] shrink-0 flex-col gap-2.5">
          <div className="rounded-xl border border-zinc-200 bg-white p-3.5 dark:border-zinc-800 dark:bg-zinc-950">
            <div className="flex items-center justify-between">
              <span className="text-[12.5px] font-medium text-zinc-900 dark:text-zinc-100">Managed proxy</span>
              <Chip>managed_proxy</Chip>
            </div>
            <div className="mt-2 flex flex-wrap gap-1.5">
              <Chip>pool</Chip>
              <Chip>country</Chip>
              <Chip>sticky</Chip>
            </div>
            <div className="mt-2 text-[11px] leading-4 text-zinc-400 dark:text-zinc-500">H provisions it; credentials never touch your requests</div>
          </div>
          <div className="text-center text-[10.5px] uppercase tracking-[0.12em] text-zinc-400 dark:text-zinc-500">or</div>
          <div className="rounded-xl border border-zinc-200 bg-white p-3.5 dark:border-zinc-800 dark:bg-zinc-950">
            <div className="flex items-center justify-between">
              <span className="text-[12.5px] font-medium text-zinc-900 dark:text-zinc-100">Bring your own</span>
              <Chip>proxy_url</Chip>
            </div>
            <div className="mt-2 text-[11px] leading-4 text-zinc-400 dark:text-zinc-500">a proxy you operate, credentials inline</div>
          </div>
        </div>

        <ArrowRight />

        <div className="flex w-[180px] shrink-0 flex-col self-center rounded-xl border border-zinc-200 bg-white p-4 dark:border-zinc-800 dark:bg-zinc-950">
          <div className="flex items-center gap-2 text-[13.5px] font-medium text-zinc-900 dark:text-zinc-100">
            <span className="text-zinc-500 dark:text-zinc-400">
              <svg className="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><rect width="20" height="14" x="2" y="3" rx="2" /><line x1="8" x2="16" y1="21" y2="21" /><line x1="12" x2="12" y1="17" y2="21" /></svg>
            </span>
            <span>Target site</span>
          </div>
          <div className="mt-1 text-[11.5px] leading-4 text-zinc-400 dark:text-zinc-500">sees the proxy's exit IP, not the platform's</div>
          <div className="mt-3 text-[11px] leading-4 text-zinc-400 dark:text-zinc-500">unblocks IP-blocked and geofenced sites</div>
        </div>
      </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](/computer-use-agents/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](/computer-use-agents/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={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": "us-browser",
      "kind": "web",
      "network": {"managed_proxy": {"pool": "residential", "country": "US"}}
    }'
  ```

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

  ```python Python theme={null}
  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={null}
  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="/computer-use-agents/browser/configuration" horizontal>
  The rest of the browser environment: fields, modes, and actions.
</Card>