Overview

Kernel proxies enable you to route browser traffic through different types of proxy servers, providing enhanced privacy, flexibility, and bot detection avoidance. Proxies can be created once and reused across multiple browser sessions.

Proxy Types

Kernel supports four types of proxies:

1. Datacenter - Traffic routed through commercial data centers
2. ISP - Traffic routed through data centers, using residential IP addresses leased from from internet service providers
3. Residential - Traffic routed through real residential IP addresses
4. Custom - Your own proxy servers

Datacenter has the fastest speed, while residential is least detectable. ISP is a balance between the two options, with less-flexible geotargeting. Kernel recommends to use the first option in the list that works for your use case.

1. Create a proxy

Create a proxy configuration from the types above that can be reused across browser sessions:

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const proxy = await kernel.proxies.create({ type: 'datacenter' });
console.log(proxy.id);

from kernel import Kernel

kernel = Kernel()

proxy = kernel.proxies.create(type="datacenter")
print(proxy.id)

2. List your proxies

View all proxy configurations in your organization:

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const proxies = await kernel.proxies.list();
console.log(proxies);

from kernel import Kernel

kernel = Kernel()

proxies = kernel.proxies.list()
print(proxies)

3. Use with browsers

Once created, you can attach a proxy to any browser session using the proxy_id parameter:

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const proxy = await kernel.proxies.create({
  type: 'residential',
  name: 'my-us-residential',
  config: {
    country: 'US',
  },
});

const browser = await kernel.browsers.create({
  proxy_id: proxy.id,
});

from kernel import Kernel

kernel = Kernel()

proxy = kernel.proxies.create(
    type="residential",
    name="my-us-residential",
    config={
        "country": "US",
    }
)

browser = kernel.browsers.create(proxy_id=proxy.id)

4. Bypass hosts

Configure specific hostnames to bypass the proxy and connect directly. This is useful for accessing internal services, metadata endpoints, or reducing latency for trusted domains.

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const proxy = await kernel.proxies.create({
  type: 'datacenter',
  name: 'proxy-with-bypass',
  config: {
    country: 'US',
  },
  bypass_hosts: [
    'localhost',
    'internal.company.local',
    'metadata.google.internal',
    '*.amazonaws.com',
  ],
});

from kernel import Kernel

kernel = Kernel()

proxy = kernel.proxies.create(
    type="datacenter",
    name="proxy-with-bypass",
    config={
        "country": "US",
    },
    bypass_hosts=[
        "localhost",
        "internal.company.local",
        "metadata.google.internal",
        "*.amazonaws.com",
    ]
)

Bypass host rules

• Exact hostnames: example.com, api.service.local
• Wildcard subdomains: *.example.com matches api.example.com, cdn.example.com, etc.
• Maximum 100 entries per proxy
• Maximum 253 characters per hostname
• Hostnames are case-insensitive and automatically normalized
• Ports, paths, and URL schemes are not allowed
• IP addresses are not supported—use hostnames only

Bypass hosts is available on Start-Up and Enterprise plans.

5. Update a browser’s proxy

You can hot-swap the proxy on a running browser session without restarting it. This updates the proxy configuration immediately — all subsequent network requests from the browser will use the new proxy.

The browser’s network is momentarily disconnected during a proxy hot swap. Any in-flight requests may fail.

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

// Create two proxy configurations
const proxyA = await kernel.proxies.create({
  type: 'isp',
  name: 'proxy-a',
  config: { country: 'US' },
});

const proxyB = await kernel.proxies.create({
  type: 'residential',
  name: 'proxy-b',
  config: { country: 'DE' },
});

// Launch a browser with the first proxy
const browser = await kernel.browsers.create({
  proxy_id: proxyA.id,
});

// Hot-swap to a different proxy
await kernel.browsers.update(browser.session_id, {
  proxy_id: proxyB.id,
});

// Remove the proxy entirely (route directly to the internet)
await kernel.browsers.update(browser.session_id, {
  proxy_id: '',
});

from kernel import Kernel

kernel = Kernel()

# Create two proxy configurations
proxy_a = kernel.proxies.create(
    type="isp",
    name="proxy-a",
    config={"country": "US"},
)

proxy_b = kernel.proxies.create(
    type="residential",
    name="proxy-b",
    config={"country": "DE"},
)

# Launch a browser with the first proxy
browser = kernel.browsers.create(
    proxy_id=proxy_a.id,
)

# Hot-swap to a different proxy
kernel.browsers.update(
    browser.session_id,
    proxy_id=proxy_b.id,
)

# Remove the proxy entirely (route directly to the internet)
kernel.browsers.update(
    browser.session_id,
    proxy_id="",
)

The update is synchronous — when the call returns, the proxy swap is fully applied and all new browser traffic routes through the updated proxy. The swap typically completes in 2–3 seconds.

If you swap the proxy on a browser acquired from a pool, the browser will be reset back to the pool’s default proxy configuration when it is released. Releasing the browser will be delayed by the swap duration (~2-3 seconds) while the proxy is restored to the pool default.

6. Delete a proxy

When no longer needed, delete the proxy configuration:

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

await kernel.proxies.delete('id');

from kernel import Kernel

kernel = Kernel()
kernel.proxies.delete("id")

Deleting a proxy immediately reconfigures associated browsers to route directly to the internet.