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:

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,
});

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:

Typescript/Javascript

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

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:

Typescript/Javascript

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

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):

Typescript/Javascript

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

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:

Typescript/Javascript

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

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.

Bypass hosts

Configure specific hostnames to bypass the proxy and connect directly:

Typescript/Javascript

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

See the overview for full bypass host rules and examples.