Skip to main content
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: 
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: 
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: 
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): 
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: 
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.