Route the browser through a proxy

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’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 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:

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

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)

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);

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:

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

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)

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);

Next steps

Browser configuration

The rest of the browser environment: fields, modes, and actions.

​Managed proxy

​Bring your own proxy

​Next steps

Browser configuration

Managed proxy

Bring your own proxy

Next steps