Egress Allowlists

​

Create a browser with an allowlist

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const browser = await kernel.browsers.create({
  start_url: 'https://shop.example.com/orders',
  network: {
    allowed_hosts: ['shop.example.com', '*.shop.example.com', 'payments.example.net'],
  },
});

console.log(browser.network?.allowed_hosts);

from kernel import Kernel

kernel = Kernel()

browser = kernel.browsers.create(
    start_url="https://shop.example.com/orders",
    network={
        "allowed_hosts": ["shop.example.com", "*.shop.example.com", "payments.example.net"],
    },
)

print(browser.network.allowed_hosts)

​

Supported entries

• Exact hostnames: shop.example.com
• A single leading wildcard: *.example.com matches subdomains at any depth, such as api.example.com and cdn.eu.example.com, but not example.com itself. Add both entries to allow a domain and its subdomains.
• Public IPv4 addresses: 203.0.113.10
• Bracketed public IPv6 addresses: [2001:4860:4860::8888]
• Canonical public CIDRs: 8.8.4.0/24 or 2001:4860::/32

• An empty list ([]). Omit allowed_hosts for unfiltered egress.
• Wildcards over any public suffix, including provider domains such as *.github.io, *.cloudfront.net, *.vercel.app, and *.herokuapp.com. List the specific host instead, such as d111111abcdef8.cloudfront.net.
• Private, loopback, link-local, and other reserved IP ranges. To reach private services, use private networking.
• Entries that overlap network.private_hosts. Private hosts bypass Kernel’s egress proxy, so an allowlist can’t filter them.
• Chrome policies in chrome_policy that can send traffic around the egress proxy: WebRtcIPHandling and WebRtcIPHandlingUrl for WebRTC, and DnsOverHttpsMode (unless it’s off), DnsOverHttpsTemplates, DnsOverHttpsTemplatesWithIdentifiers, and DnsOverHttpsSalt for secure DNS. Adding an allowlist with update() to a browser created with one of them is rejected too.
• Non-canonical forms, such as CIDRs with host bits set or IPv4-mapped IPv6 addresses.

​

When a destination is blocked

​

Change the allowlist during a session

await kernel.browsers.update(browser.session_id, {
  network: {
    allowed_hosts: ['shop.example.com', '*.shop.example.com'],
  },
});

kernel.browsers.update(
    browser.session_id,
    network={
        "allowed_hosts": ["shop.example.com", "*.shop.example.com"],
    },
)

• New requests to destinations the new list doesn’t allow are refused within a few seconds, and Kernel closes open connections to them within about 30 seconds. Connections to destinations it still allows, such as an open WebSocket, stay open.
• During a Kernel deploy, an open connection to a removed host can survive for up to 10 minutes. New requests to it are still refused within a few seconds.
• A start_url in the same update must be allowed by the new list. Kernel navigates to it only after the new list is in effect.
• Omitting allowed_hosts leaves the list unchanged, and [] is rejected.
• If the update fails with a 500, retry it. The new list might already apply to some requests.

await kernel.browsers.update(browser.session_id, {
  network: { allowed_hosts: null },
});

kernel.browsers.update(
    browser.session_id,
    network={"allowed_hosts": None},
)

​

Keep the allowlist out of the agent’s reach

​

Limitations

• Only Chromium’s HTTP(S) and WebSocket traffic through Kernel’s egress proxy is filtered. The browser VM has a direct route to the internet, so anything else can leave it unfiltered, including:
  • Programs you run in the browser VM, for example with process execution.
  • Browser contexts created over CDP with their own proxy settings, such as Playwright’s browser.newContext({ proxy }).
  • Extensions with the proxy permission, which can switch Chromium to direct connections.
  • DNS lookups that don’t go through the proxy, such as Chromium’s lookups for hosts in network.private_hosts. Requests through the egress proxy are resolved by the proxy, and Kernel rejects the Chrome policies that turn on secure DNS for allowlisted browsers.
• Destinations in network.private_hosts, including the default private ranges, are reached directly and aren’t filtered. If the session doesn’t need private routes, set private_hosts to [] so all traffic goes through the egress proxy.
• Requests to Kernel’s own browser infrastructure, which features such as CAPTCHA solving and telemetry depend on, are always allowed.
• Browser pools don’t support allowlists. You can’t set one on a pool, or add one with update() to a browser acquired from a pool.