Egress Allowlists

​

Create a browser with an allowlist

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const kernelBrowser = 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(kernelBrowser.network?.allowed_hosts);

from kernel import Kernel

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(kernel_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: 8.8.8.8
• 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.
• Non-canonical forms, such as CIDRs with host bits set or IPv4-mapped IPv6 addresses.

​

When a destination is blocked

​

CAPTCHAs

• reCAPTCHA: www.google.com and www.gstatic.com
• hCaptcha: hcaptcha.com and *.hcaptcha.com
• Cloudflare Turnstile: challenges.cloudflare.com

​

Change the allowlist during a session

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

kernel.browsers.update(
    kernel_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(kernelBrowser.session_id, {
  network: { allowed_hosts: null },
});

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

​

Use allowlists with browser pools

const pool = await kernel.browserPools.create({
  name: 'orders-pool',
  size: 5,
  start_url: 'https://shop.example.com/orders',
  network: {
    allowed_hosts: ['shop.example.com', '*.shop.example.com', 'payments.example.net'],
  },
});

pool = kernel.browser_pools.create(
    name="orders-pool",
    size=5,
    start_url="https://shop.example.com/orders",
    network={
        "allowed_hosts": ["shop.example.com", "*.shop.example.com", "payments.example.net"],
    },
)

await kernel.browserPools.update(pool.id, {
  network: {
    allowed_hosts: ['shop.example.com', '*.shop.example.com'],
  },
});

kernel.browser_pools.update(
    pool.id,
    network={
        "allowed_hosts": ["shop.example.com", "*.shop.example.com"],
    },
)

​

Keep the allowlist out of the agent’s reach

​

Limitations

• Enforcement covers Chromium’s HTTP(S) and WebSocket traffic through Kernel’s egress proxy, not all traffic leaving the browser VM. This isn’t full VM-level network isolation:
  • Code executing inside the browser VM, including through process execution, can send traffic directly and disable the VM-side CDP restriction.
  • Extensions with the proxy permission can override Chromium’s proxy settings and switch to direct connections.
  • DNS lookups that don’t go through the proxy aren’t filtered, 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.
• CDP context creation with proxyServer or proxyBypassList is refused on allowlisted browsers, including empty/direct settings and Playwright’s browser.newContext({ proxy }). Ordinary context creation is permitted. Browsers without an allowlist retain normal custom-proxy context behavior; code executing inside the VM can disable this restriction.
• 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 [] to remove those browser proxy bypasses. This doesn’t restrict direct traffic from code executing inside the VM.
• Requests to Kernel’s own browser infrastructure, which features such as CAPTCHA solving and telemetry depend on, are always allowed.