Residential Proxies

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

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). Conflicts with city and 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.

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.