Residential Proxies

Residential proxies route traffic through real residential IP addresses. They support advanced targeting options including city, state, and operating system.

Proxy provider selection

KERNEL routes residential proxy traffic across multiple providers. This expands destination coverage and makes the proxy network more reliable. For each session, KERNEL chooses one of the proxy providers to be the preferred provider for that session, based on KERNEL’s desired proxy traffic split. When making a connection through the proxy network to a target site, KERNEL will choose a different provider for this connection than the session’s default if the default does not support the target destination or provider has an outage. Different destinations within a browser session may use different providers.

IP consistency

Open connections stay on their current provider and exit IP. Routing updates affect new connections rather than interrupting open ones.
New connections may use a different exit IP because of failover, routing updates, sticky-session expiry, or residential device availability.
Different destinations may use different providers and exit IPs within the same browser session.

If you need a consistent exit IP across connections and browser sessions, use an ISP proxy instead.

Configuration

Create a residential proxy with a target country:

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)

package main

import (
	"context"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
		Type: kernel.ProxyNewParamsTypeResidential,
		Name: kernel.String("my-us-residential"),
		Config: kernel.ProxyNewParamsConfigUnion{
			OfProxyNewsConfigResidentialProxyConfig: &kernel.ProxyNewParamsConfigResidentialProxyConfig{
				Country: kernel.String("US"),
			},
		},
	})
	if err != nil {
		panic(err)
	}

	browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
		ProxyID: kernel.String(proxy.ID),
	})
	if err != nil {
		panic(err)
	}
	_ = browser
}

Configuration Parameters

country - ISO 3166 country code. Must be provided when providing other targeting options.
state - Two-letter state code. Only supported for US.
city - City name (lowercase, no spaces, e.g., sanfrancisco, newyork).
zip - US ZIP code (5 digits). Can only be used with country set to US. Cannot be combined with city or state.
asn - Autonomous System Number. Conflicts with city and state.
bypass_hosts (optional) - Array of hostnames that bypass the proxy and connect directly (max 100 entries)

Advanced Targeting Examples

Kernel recommends using the least-specific targeting configuration that works for your use case. The more specific a configuration, the less available IPs there are, increasing the chance of a slow connection or no available connection (no_peer connection error).

Target by City

Route traffic through a specific city:

const proxy = await kernel.proxies.create({
  type: 'residential',
  name: 'la-residential',
  config: {
    country: 'US',
    state: 'CA',
    city: 'los_angeles'
  }
});

proxy = kernel.proxies.create(
    type='residential',
    name='la-residential',
    config={
        'country': 'US',
        'state': 'CA',
        'city': 'los_angeles'
    }
)

proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
	Type: kernel.ProxyNewParamsTypeResidential,
	Name: kernel.String("la-residential"),
	Config: kernel.ProxyNewParamsConfigUnion{
		OfProxyNewsConfigResidentialProxyConfig: &kernel.ProxyNewParamsConfigResidentialProxyConfig{
			Country: kernel.String("US"),
			State:   kernel.String("CA"),
			City:    kernel.String("los_angeles"),
		},
	},
})
if err != nil {
	panic(err)
}
_ = proxy

If the city name is not matched, the API will return the best 10 city names from the state to help you find the correct city identifier.

Target by State

Route traffic through a specific state:

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

proxy = kernel.proxies.create(
    type='residential',
    name='ny-residential',
    config={
        'country': 'US',
        'state': 'NY'
    }
)

proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
	Type: kernel.ProxyNewParamsTypeResidential,
	Name: kernel.String("ny-residential"),
	Config: kernel.ProxyNewParamsConfigUnion{
		OfProxyNewsConfigResidentialProxyConfig: &kernel.ProxyNewParamsConfigResidentialProxyConfig{
			Country: kernel.String("US"),
			State:   kernel.String("NY"),
		},
	},
})
if err != nil {
	panic(err)
}
_ = proxy

If the state name is not matched, the API will return the most-available 10 states.

Target by ASN

Route traffic through a specific Autonomous System Number (ISP):

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

proxy = kernel.proxies.create(
    type='residential',
    name='comcast-residential',
    config={
        'country': 'US',
        'asn': 'AS7922'
    }
)

proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
	Type: kernel.ProxyNewParamsTypeResidential,
	Name: kernel.String("comcast-residential"),
	Config: kernel.ProxyNewParamsConfigUnion{
		OfProxyNewsConfigResidentialProxyConfig: &kernel.ProxyNewParamsConfigResidentialProxyConfig{
			Country: kernel.String("US"),
			Asn:     kernel.String("AS7922"),
		},
	},
})
if err != nil {
	panic(err)
}
_ = proxy

If the ASN is not matched, the API will return the most-available 10 examples.

Target by ZIP code

Route traffic through a specific US ZIP code area:

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

proxy = kernel.proxies.create(
    type='residential',
    name='nyc-residential',
    config={
        'country': 'US',
        'zip': '10001'
    }
)

proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
	Type: kernel.ProxyNewParamsTypeResidential,
	Name: kernel.String("nyc-residential"),
	Config: kernel.ProxyNewParamsConfigUnion{
		OfProxyNewsConfigResidentialProxyConfig: &kernel.ProxyNewParamsConfigResidentialProxyConfig{
			Country: kernel.String("US"),
			Zip:     kernel.String("10001"),
		},
	},
})
if err != nil {
	panic(err)
}
_ = proxy

ZIP code targeting is US-only and cannot be combined with state or city. The exit IP will be in the geographic area of the requested ZIP code, but the IP’s exact ZIP may differ slightly (e.g., requesting 90210 may route through 90401 in the same metro area).

Not all ZIP codes have available residential IPs. If a ZIP code is unavailable, proxy creation will fail with a message suggesting alternatives: a nearby ZIP, city/state targeting, or country-only targeting.

.gov support

Residential proxies with no targeting, country-only targeting, or US state targeting automatically route .gov requests through a compatible upstream provider. ZIP, ASN, and non-US state targeting may return restricted_route_unavailable. You may check proxy health against a .gov URL before starting a browser.

Bypass hosts

Configure specific hostnames to bypass the proxy and connect directly:

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

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

proxy, err := client.Proxies.New(ctx, kernel.ProxyNewParams{
	Type: kernel.ProxyNewParamsTypeResidential,
	Name: kernel.String("residential-with-bypass"),
	Config: kernel.ProxyNewParamsConfigUnion{
		OfProxyNewsConfigResidentialProxyConfig: &kernel.ProxyNewParamsConfigResidentialProxyConfig{
			Country: kernel.String("US"),
		},
	},
	BypassHosts: []string{
		"localhost",
		"metadata.google.internal",
		"*.internal.company.com",
	},
})
if err != nil {
	panic(err)
}
_ = proxy

See the overview for full bypass host rules and examples.

Overview

Working with your browser

Integrations

deploying your agent

Agent Skills

Community

Info

Residential Proxies

Proxy provider selection

IP consistency

Configuration

Configuration Parameters

Advanced Targeting Examples

Target by City

Target by State

Target by ASN

Target by ZIP code

.gov support

Bypass hosts

​Proxy provider selection

​IP consistency

​Configuration

​Configuration Parameters

​Advanced Targeting Examples

​Target by City

​Target by State

​Target by ASN

​Target by ZIP code

​.gov support

​Bypass hosts

Proxy provider selection

IP consistency

Configuration

Configuration Parameters

Advanced Targeting Examples

Target by City

Target by State

Target by ASN

Target by ZIP code

.gov support

Bypass hosts