> ## Documentation Index
> Fetch the complete documentation index at: https://www.kernel.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-Host Proxy Routes

> Send selected browser destinations through different proxies

Use `network.proxy_routes` when a browser needs a different proxy for specific destination hosts. Create a proxy configuration first, then choose it by ID or name for each route. Hosts that don't match a route use the browser's top-level `proxy` setting (or the browser default if you omit `proxy`).

## Configure routes when creating a browser

This example sends requests to `catalog.example.com` and subdomains of `partners.example.com` through a datacenter proxy. Other requests use direct egress.

```typescript TypeScript theme={null}
import Kernel from '@onkernel/sdk';

const kernel = new Kernel();
const routeProxy = await kernel.proxies.create({ type: 'datacenter' });

const browser = await kernel.browsers.create({
  proxy: { mode: 'direct' },
  network: {
    proxy_routes: [
      {
        hosts: ['catalog.example.com', '*.partners.example.com'],
        proxy: { id: routeProxy.id },
      },
    ],
  },
});

console.log(browser.session_id);
```

```python Python theme={null}
from kernel import Kernel

kernel = Kernel()
route_proxy = kernel.proxies.create(type="datacenter")

browser = kernel.browsers.create(
    proxy={"mode": "direct"},
    network={
        "proxy_routes": [
            {
                "hosts": ["catalog.example.com", "*.partners.example.com"],
                "proxy": {"id": route_proxy.id},
            }
        ]
    },
)

print(browser.session_id)
```

You can use `proxy: { name: "..." }` in a route instead of an ID. The name must resolve to exactly one active proxy in the browser's project; use an ID when names might be ambiguous. A route can't select direct egress—set the top-level `proxy` to `{ mode: "direct" }` for unmatched hosts instead.

Routes take effect after browser setup. A `start_url` and other setup traffic use the top-level proxy, even if their hosts match a route.

## Host matching and limits

* Each route has 1–50 hosts, and a browser can have up to 10 routes.
* Use exact hostnames or a leading wildcard such as `*.partners.example.com`. A wildcard matches subdomains, not `partners.example.com` itself. Add both patterns if you need both.
* Matching ignores ports. An exact hostname wins over a wildcard; among wildcards, the longer matching suffix wins. Route order doesn't affect the result.
* A host pattern can appear in only one route. Route hosts can't overlap with explicitly configured `network.private_hosts` entries.
* If a route's proxy becomes unavailable, requests to matching hosts fail rather than falling back to the top-level proxy.

`network.proxy_routes` works on browsers created through `POST /browsers`, not browser pools. You can't change the routes after creating a browser.

> [!NOTE]
>
> To reach a private service through a VPN or tunnel inside the browser, use [`network.private_hosts`](https://www.kernel.sh/docs/browsers/private-networking). Unlike `proxy_routes`, it sends matching traffic through the browser session's own network, not through a selected proxy. A proxy's [`bypass_hosts`](https://www.kernel.sh/docs/proxies/overview#bypass-hosts) instead bypasses that proxy for Kernel-managed direct egress.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.