Residential Proxies

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

Residential proxies use rotating exit IPs — each new connection may route through a different residential IP address within your targeted region. This is because residential traffic is routed through real consumer devices that may go offline at any time, so the network assigns a new available exit node per connection. This means different browser tabs or requests to different websites within the same session can show different public IPs. If you need a consistent IP address across all connections, use an ISP proxy instead.

IP Rotation Behavior

Residential proxies assign a new exit IP for each new TCP connection. In practice:

Same website across tabs: Tabs connecting to the same domain typically share a TCP connection (via HTTP connection pooling), so they usually see the same IP.
Different websites across tabs: Tabs connecting to different domains open separate connections, so they will likely exit through different residential IPs.
Reconnections: If a connection is closed and re-established (e.g., after a timeout or page idle), the new connection may get a different exit IP.

This behavior is inherent to residential proxy networks, where traffic is routed through real consumer devices that come online and offline dynamically.

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.

Restricted destination routing

Residential proxies automatically route restricted destinations through a compatible upstream provider. This covers .gov, a set of country government domains such as gov.uk, gov.au, gc.ca, gouv.fr, and go.jp, and a set of banking, payment, postal, and other commonly blocked destinations. Routing is available on proxies with no targeting, country-only targeting, US state targeting, or city targeting — city-targeted proxies get it only when a compatible route exists for that city at creation time. ZIP and ASN targeting, and state targeting outside the US, cannot carry the route at all; restricted destinations on those proxies use the proxy’s normal provider and fail with provider_blacklisted if it blocks them. The covered set is maintained by Kernel and is not exhaustive. Government coverage outside .gov is domain by domain rather than by suffix, so a government domain that isn’t in the set stays on the normal provider even when a related one is routed. Request an exception to have a destination added.

How routing affects exit IPs

Routed destinations don’t follow the rotation behavior above:

The exit IP comes from the compatible provider’s pool, not the pool serving the rest of your session. Only the covered hostname moves — subresources, CDNs, and redirects to hostnames outside the set keep the session’s normal exit IP, so one page load can use both. A login that redirects through an identity provider outside the set crosses providers mid-flow.
A routed destination keeps one sticky exit IP per registrable domain rather than rotating per connection. Two covered destinations in one session — two government agencies, for example — get two different IPs.
Stickiness lasts roughly ten minutes after the last request to that destination. A session that idles past that and then resumes can continue from a different IP, which a site that pins a login to an IP might treat as a new session.
Bypass hosts take precedence: a covered destination listed there connects through Kernel’s direct egress instead of being routed.

Check proxy health against the destination URL before starting a browser. The check resolves the route the same way a session does, so it confirms the destination is covered and the route is available.

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

Migrations

deploying your agent

Agent Skills

Community

Info

Residential Proxies

IP Rotation Behavior

Configuration

Configuration Parameters

Advanced Targeting Examples

Target by City

Target by State

Target by ASN

Target by ZIP code

Restricted destination routing

How routing affects exit IPs

Bypass hosts

​IP Rotation Behavior

​Configuration

​Configuration Parameters

​Advanced Targeting Examples

​Target by City

​Target by State

​Target by ASN

​Target by ZIP code

​Restricted destination routing

​How routing affects exit IPs

​Bypass hosts

IP Rotation Behavior

Configuration

Configuration Parameters

Advanced Targeting Examples

Target by City

Target by State

Target by ASN

Target by ZIP code

Restricted destination routing

How routing affects exit IPs

Bypass hosts