From abbed72f99e1ac163058fa2d7630671fb2fc2e88 Mon Sep 17 00:00:00 2001 From: "tembo-io[bot]" <208362400+tembo-io[bot]@users.noreply.github.com> Date: Sat, 27 Sep 2025 22:14:58 +0000 Subject: [PATCH 01/12] Add SDK documentation for Proxies feature - Create new Proxies documentation section with pages for each proxy type (datacenter, isp, residential, mobile, custom) - Add 'Configure proxy' page under Browsers section explaining how to use proxies with browsers - Update navigation in docs.json to include new Proxies section and Configure proxy page - Include code examples in both TypeScript/JavaScript and Python for all proxy types - Document configuration parameters, use cases, benefits and limitations for each proxy type --- browsers/configure-proxy.mdx | 291 +++++++++++++++++++++++++++++++++++ docs.json | 12 ++ proxies/custom.mdx | 206 +++++++++++++++++++++++++ proxies/datacenter.mdx | 118 ++++++++++++++ proxies/isp.mdx | 133 ++++++++++++++++ proxies/mobile.mdx | 236 ++++++++++++++++++++++++++++ proxies/overview.mdx | 93 +++++++++++ proxies/residential.mdx | 199 ++++++++++++++++++++++++ 8 files changed, 1288 insertions(+) create mode 100644 browsers/configure-proxy.mdx create mode 100644 proxies/custom.mdx create mode 100644 proxies/datacenter.mdx create mode 100644 proxies/isp.mdx create mode 100644 proxies/mobile.mdx create mode 100644 proxies/overview.mdx create mode 100644 proxies/residential.mdx diff --git a/browsers/configure-proxy.mdx b/browsers/configure-proxy.mdx new file mode 100644 index 0000000..c5bfb56 --- /dev/null +++ b/browsers/configure-proxy.mdx @@ -0,0 +1,291 @@ +--- +title: "Configure Proxy" +--- + +Kernel browsers can be configured to route traffic through proxies for enhanced privacy, geographic targeting, and bot detection avoidance. You can either create reusable proxy configurations or use them directly with browsers. + +## Using proxies with browsers + +To use a proxy with a browser, specify the `proxy_id` parameter when creating the browser session: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +// First, create a proxy configuration +const proxy = await kernel.proxies.create({ + type: 'residential', + name: 'US Residential', + config: { + country: 'US' + } +}); + +// Then use it with a browser +const browser = await kernel.browsers.create({ + proxy_id: proxy.id, + stealth: true // Recommended when using proxies +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +# First, create a proxy configuration +proxy = client.proxies.create( + type='residential', + name='US Residential', + config={ + 'country': 'US' + } +) + +# Then use it with a browser +browser = client.browsers.create( + proxy_id=proxy.id, + stealth=True # Recommended when using proxies +) +``` + + + +## Reusing proxy configurations + +Once created, proxy configurations can be reused across multiple browser sessions: + + + +```typescript Typescript/Javascript +// Get existing proxies +const proxies = await kernel.proxies.list(); +const usProxy = proxies.find(p => p.name === 'US Residential'); + +// Create multiple browsers with the same proxy +const browsers = []; +for (let i = 0; i < 5; i++) { + const browser = await kernel.browsers.create({ + proxy_id: usProxy.id + }); + browsers.push(browser); +} +``` + +```Python Python +# Get existing proxies +proxies = client.proxies.list() +us_proxy = next(p for p in proxies if p.name == 'US Residential') + +# Create multiple browsers with the same proxy +browsers = [] +for i in range(5): + browser = client.browsers.create( + proxy_id=us_proxy.id + ) + browsers.append(browser) +``` + + + +## Best practices + +### 1. Combine with stealth mode + +When using proxies, always enable stealth mode for better bot detection avoidance: + + + +```typescript Typescript/Javascript +const browser = await kernel.browsers.create({ + proxy_id: proxy.id, + stealth: true +}); +``` + +```Python Python +browser = client.browsers.create( + proxy_id=proxy.id, + stealth=True +) +``` + + + +### 2. Match proxy type to use case + +Choose the appropriate proxy type based on your needs: + +- **Mobile**: Best for avoiding detection, slowest +- **Residential**: Great for avoiding detection, moderate speed +- **ISP**: Good balance of speed and detection avoidance +- **Datacenter**: Fastest but most easily detected +- **Custom**: Use your own proxy infrastructure + +### 3. Geographic consistency + +Ensure proxy location matches your browser profile's location: + + + +```typescript Typescript/Javascript +// Create a profile with US location +const profile = await kernel.profiles.create({ + name: 'US User', + locale: 'en-US', + timezone: 'America/New_York' +}); + +// Use a US proxy to match +const proxy = await kernel.proxies.create({ + type: 'residential', + config: { + country: 'US', + state: 'NY' + } +}); + +// Create browser with matching profile and proxy +const browser = await kernel.browsers.create({ + profile_id: profile.id, + proxy_id: proxy.id +}); +``` + +```Python Python +# Create a profile with US location +profile = client.profiles.create( + name='US User', + locale='en-US', + timezone='America/New_York' +) + +# Use a US proxy to match +proxy = client.proxies.create( + type='residential', + config={ + 'country': 'US', + 'state': 'NY' + } +) + +# Create browser with matching profile and proxy +browser = client.browsers.create( + profile_id=profile.id, + proxy_id=proxy.id +) +``` + + + +## Proxy rotation strategies + +### Sequential rotation + +Rotate through proxies in order: + + + +```typescript Typescript/Javascript +const proxies = await kernel.proxies.list(); +let currentIndex = 0; + +function getNextProxy() { + const proxy = proxies[currentIndex]; + currentIndex = (currentIndex + 1) % proxies.length; + return proxy; +} + +// Use different proxy for each task +for (const task of tasks) { + const proxy = getNextProxy(); + const browser = await kernel.browsers.create({ + proxy_id: proxy.id + }); + await performTask(browser, task); + await browser.close(); +} +``` + +```Python Python +proxies = client.proxies.list() +current_index = 0 + +def get_next_proxy(): + global current_index + proxy = proxies[current_index] + current_index = (current_index + 1) % len(proxies) + return proxy + +# Use different proxy for each task +for task in tasks: + proxy = get_next_proxy() + browser = client.browsers.create( + proxy_id=proxy.id + ) + await perform_task(browser, task) + browser.close() +``` + + + +### Random rotation + +Randomly select proxies for better distribution: + + + +```typescript Typescript/Javascript +const proxies = await kernel.proxies.list(); + +function getRandomProxy() { + const index = Math.floor(Math.random() * proxies.length); + return proxies[index]; +} + +const browser = await kernel.browsers.create({ + proxy_id: getRandomProxy().id +}); +``` + +```Python Python +import random + +proxies = client.proxies.list() + +def get_random_proxy(): + return random.choice(proxies) + +browser = client.browsers.create( + proxy_id=get_random_proxy().id +) +``` + + + +## Troubleshooting + +### Proxy connection failures + +If a browser fails to connect through a proxy: + +1. Verify the proxy configuration is correct +2. Check if the proxy type supports your target site +3. Try a different proxy type or location +4. Ensure custom proxies are accessible + +### Performance issues + +If experiencing slow performance: + +1. Consider using faster proxy types (ISP or datacenter) +2. Choose proxy locations closer to target servers +3. Reduce the number of concurrent browsers per proxy +4. Monitor proxy health and rotate out slow proxies + +## Related resources + +- [Proxies Overview](/proxies/overview) - Learn about proxy types and capabilities +- [Stealth Mode](/browsers/stealth) - Enhance bot detection avoidance +- [Browser Profiles](/browsers/profiles) - Create consistent browser identities \ No newline at end of file diff --git a/docs.json b/docs.json index c0385d1..0970742 100644 --- a/docs.json +++ b/docs.json @@ -60,12 +60,24 @@ "browsers/standby", "browsers/persistence", "browsers/profiles", + "browsers/configure-proxy", "browsers/termination", "browsers/file-io", "browsers/live-view", "browsers/replays" ] }, + { + "group": "Proxies", + "pages": [ + "proxies/overview", + "proxies/datacenter", + "proxies/isp", + "proxies/residential", + "proxies/mobile", + "proxies/custom" + ] + }, { "group": "App Platform", "pages": [ diff --git a/proxies/custom.mdx b/proxies/custom.mdx new file mode 100644 index 0000000..e5cbc97 --- /dev/null +++ b/proxies/custom.mdx @@ -0,0 +1,206 @@ +--- +title: "Custom Proxies" +--- + +Custom proxies allow you to use your own proxy servers with Kernel browsers. This is useful when you have existing proxy infrastructure or specific proxy requirements not covered by Kernel's managed options. + +## When to use + +- You have your own proxy infrastructure +- Need to use specific proxy providers +- Require proxies with special configurations +- Want to use SOCKS5 or HTTP proxies + +## Configuration + +Custom proxies require host, port, and optional authentication: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'custom', + name: 'My Private Proxy', + config: { + host: 'proxy.example.com', + port: 8080, + username: 'user123', + password: 'secure_password' + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='custom', + name='My Private Proxy', + config={ + 'host': 'proxy.example.com', + 'port': 8080, + 'username': 'user123', + 'password': 'secure_password' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Configuration Parameters + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `host` | Yes | Proxy server hostname or IP address | +| `port` | Yes | Proxy server port | +| `username` | No | Username for proxy authentication | +| `password` | No* | Password for proxy authentication | + +*Note: When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. + +## Example: Using IP-based proxy + + + +```typescript Typescript/Javascript +const proxy = await kernel.proxies.create({ + type: 'custom', + name: 'Direct IP Proxy', + config: { + host: '192.168.1.100', + port: 3128 + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +proxy = client.proxies.create( + type='custom', + name='Direct IP Proxy', + config={ + 'host': '192.168.1.100', + 'port': 3128 + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Example: Rotating through multiple custom proxies + + + +```typescript Typescript/Javascript +// List of your proxy servers +const proxyServers = [ + { host: 'proxy1.example.com', port: 8080 }, + { host: 'proxy2.example.com', port: 8080 }, + { host: 'proxy3.example.com', port: 8080 } +]; + +// Create proxy configurations +const proxies = []; +for (const server of proxyServers) { + const proxy = await kernel.proxies.create({ + type: 'custom', + name: `Custom ${server.host}`, + config: { + host: server.host, + port: server.port, + username: 'shared_user', + password: 'shared_pass' + } + }); + proxies.push(proxy); +} + +// Rotate through proxies for different tasks +for (let i = 0; i < tasks.length; i++) { + const proxy = proxies[i % proxies.length]; + const browser = await kernel.browsers.create({ + proxy_id: proxy.id + }); + + // Perform task with this proxy + await performTask(browser); + await browser.close(); +} +``` + +```Python Python +# List of your proxy servers +proxy_servers = [ + {'host': 'proxy1.example.com', 'port': 8080}, + {'host': 'proxy2.example.com', 'port': 8080}, + {'host': 'proxy3.example.com', 'port': 8080} +] + +# Create proxy configurations +proxies = [] +for server in proxy_servers: + proxy = client.proxies.create( + type='custom', + name=f"Custom {server['host']}", + config={ + 'host': server['host'], + 'port': server['port'], + 'username': 'shared_user', + 'password': 'shared_pass' + } + ) + proxies.append(proxy) + +# Rotate through proxies for different tasks +for i, task in enumerate(tasks): + proxy = proxies[i % len(proxies)] + browser = client.browsers.create( + proxy_id=proxy.id + ) + + # Perform task with this proxy + await perform_task(browser) + browser.close() +``` + + + +## Security Considerations + +- Proxy passwords are encrypted and never returned in API responses +- Ensure your proxy servers use secure connections +- Regularly rotate credentials for security +- Monitor proxy usage for unauthorized access + +## Benefits + +- Use existing proxy infrastructure +- Full control over proxy configuration +- Cost-effective if you already have proxies +- Flexibility to use any proxy provider + +## Limitations + +- You're responsible for proxy reliability +- No automatic rotation or failover +- Quality depends on your proxy provider +- Must manage authentication credentials \ No newline at end of file diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx new file mode 100644 index 0000000..c35759c --- /dev/null +++ b/proxies/datacenter.mdx @@ -0,0 +1,118 @@ +--- +title: "Datacenter Proxies" +--- + +Datacenter proxies route traffic through commercial data center servers. While they offer the fastest speeds and highest reliability, they are the most easily detected by anti-bot systems. + +## When to use + +- High-volume data collection +- Speed is the primary concern +- Target sites have minimal bot detection +- Cost-effective proxy solution needed + +## Configuration + +Datacenter proxies require only a country specification: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'datacenter', + name: 'US Datacenter', + config: { + country: 'US' + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='datacenter', + name='US Datacenter', + config={ + 'country': 'US' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Supported Countries + +Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. + +## Example: Multi-region scraping + +Create multiple datacenter proxies for different regions: + + + +```typescript Typescript/Javascript +const regions = ['US', 'EU', 'JP']; +const proxies = []; + +for (const region of regions) { + const proxy = await kernel.proxies.create({ + type: 'datacenter', + name: `${region} Datacenter`, + config: { + country: region + } + }); + proxies.push(proxy); +} + +// Use different proxies for different tasks +for (const proxy of proxies) { + const browser = await kernel.browsers.create({ + proxy_id: proxy.id + }); + // Perform region-specific tasks + await browser.close(); +} +``` + +```Python Python +regions = ['US', 'EU', 'JP'] +proxies = [] + +for region in regions: + proxy = client.proxies.create( + type='datacenter', + name=f'{region} Datacenter', + config={'country': region} + ) + proxies.append(proxy) + +# Use different proxies for different tasks +for proxy in proxies: + browser = client.browsers.create( + proxy_id=proxy.id + ) + # Perform region-specific tasks + browser.close() +``` + + + +## Limitations + +- Most easily detected by anti-bot systems +- May be blocked by sites with strict bot detection +- IP addresses are from known datacenter ranges \ No newline at end of file diff --git a/proxies/isp.mdx b/proxies/isp.mdx new file mode 100644 index 0000000..f19af17 --- /dev/null +++ b/proxies/isp.mdx @@ -0,0 +1,133 @@ +--- +title: "ISP Proxies" +--- + +ISP (Internet Service Provider) proxies combine the speed of datacenter proxies with better legitimacy, as they use IP addresses assigned by real ISPs. They offer a good balance between performance and detection avoidance. + +## When to use + +- Need better detection avoidance than datacenter proxies +- Require consistent, static IP addresses +- Speed is still important +- Medium-level bot detection on target sites + +## Configuration + +ISP proxies require a country specification: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'isp', + name: 'US ISP Proxy', + config: { + country: 'US' + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='isp', + name='US ISP Proxy', + config={ + 'country': 'US' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Supported Countries + +Use ISO 3166 country codes (e.g., `US`, `GB`, `DE`) or `EU` for European Union exit nodes. + +## Example: Long-running sessions + +ISP proxies are ideal for maintaining long-running browser sessions: + + + +```typescript Typescript/Javascript +// Create ISP proxy for stable connection +const proxy = await kernel.proxies.create({ + type: 'isp', + name: 'Stable ISP', + config: { + country: 'US' + } +}); + +// Create persistent browser session +const browser = await kernel.browsers.create({ + proxy_id: proxy.id, + persistence: true, + timeout_seconds: 3600 // 1 hour +}); + +// Connect and perform long-running tasks +const playwright = await chromium.connectOverCDP(browser.cdp_ws_url); +const context = playwright.contexts()[0]; +const page = context.pages()[0]; + +// Maintain session for extended operations +await page.goto('https://example.com'); +// ... perform extended operations +``` + +```Python Python +# Create ISP proxy for stable connection +proxy = client.proxies.create( + type='isp', + name='Stable ISP', + config={ + 'country': 'US' + } +) + +# Create persistent browser session +browser = client.browsers.create( + proxy_id=proxy.id, + persistence=True, + timeout_seconds=3600 # 1 hour +) + +# Connect and perform long-running tasks +playwright_browser = playwright.chromium.connect_over_cdp(browser.cdp_ws_url) +context = playwright_browser.contexts[0] +page = context.pages[0] + +# Maintain session for extended operations +await page.goto('https://example.com') +# ... perform extended operations +``` + + + +## Benefits + +- Better than datacenter for avoiding detection +- Static IP addresses for session consistency +- High uptime and reliability +- Good speed performance + +## Limitations + +- More expensive than datacenter proxies +- Still detectable by advanced anti-bot systems +- Limited geographic granularity \ No newline at end of file diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx new file mode 100644 index 0000000..d6c92bd --- /dev/null +++ b/proxies/mobile.mdx @@ -0,0 +1,236 @@ +--- +title: "Mobile Proxies" +--- + +Mobile proxies route traffic through mobile carrier networks, providing the highest level of trust and the best bot detection avoidance. They use IP addresses from real mobile devices on cellular networks. + +## When to use + +- Accessing sites with the strongest anti-bot protection +- Mobile app automation and testing +- Need to appear as genuine mobile users +- Success rate is more important than speed + +## Configuration Options + +Mobile proxies support carrier selection and advanced targeting: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'mobile', + name: 'Verizon Mobile', + config: { + country: 'US', + carrier: 'verizon', + state: 'CA', + city: 'losangeles', + zip: '90001', + asn: '6167' + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='mobile', + name='Verizon Mobile', + config={ + 'country': 'US', + 'carrier': 'verizon', + 'state': 'CA', + 'city': 'losangeles', + 'zip': '90001', + 'asn': '6167' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Configuration Parameters + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `country` | No* | ISO 3166 country code (required if `city` is provided) | +| `carrier` | No | Mobile carrier name (see supported carriers below) | +| `state` | No | Two-letter US state code | +| `city` | No | City name without spaces | +| `zip` | No | US ZIP code | +| `asn` | No | Autonomous System Number | + +## Supported Carriers + +Major carriers worldwide are supported, including: + +**US Carriers:** +- `att` - AT&T +- `verizon` - Verizon +- `tmobile` - T-Mobile +- `sprint` - Sprint +- `comcast` - Xfinity Mobile +- `cox` - Cox Mobile + +**International Carriers:** +- `vodafone` - Vodafone +- `orange` - Orange +- `telefonica` - Telefónica +- `dt` - Deutsche Telekom +- `docomo` - NTT Docomo +- `chinamobile` - China Mobile +- `airtel` - Bharti Airtel +- `telstra` - Telstra + +[View all supported carriers in the API reference] + +## Example: Mobile app testing + +Test mobile-specific features across different carriers: + + + +```typescript Typescript/Javascript +const carriers = ['verizon', 'att', 'tmobile']; + +for (const carrier of carriers) { + const proxy = await kernel.proxies.create({ + type: 'mobile', + name: `${carrier} Mobile Test`, + config: { + country: 'US', + carrier: carrier + } + }); + + const browser = await kernel.browsers.create({ + proxy_id: proxy.id, + // Use mobile viewport + viewport: { width: 390, height: 844 } + }); + + const playwright = await chromium.connectOverCDP(browser.cdp_ws_url); + const context = playwright.contexts()[0]; + const page = context.pages()[0]; + + // Test mobile-specific features + await page.goto('https://m.example.com'); + + // Verify carrier-specific behavior + const userAgent = await page.evaluate(() => navigator.userAgent); + console.log(`Testing with ${carrier}: ${userAgent}`); + + await browser.close(); +} +``` + +```Python Python +carriers = ['verizon', 'att', 'tmobile'] + +for carrier in carriers: + proxy = client.proxies.create( + type='mobile', + name=f'{carrier} Mobile Test', + config={ + 'country': 'US', + 'carrier': carrier + } + ) + + browser = client.browsers.create( + proxy_id=proxy.id, + # Use mobile viewport + viewport={'width': 390, 'height': 844} + ) + + playwright_browser = playwright.chromium.connect_over_cdp(browser.cdp_ws_url) + context = playwright_browser.contexts[0] + page = context.pages[0] + + # Test mobile-specific features + await page.goto('https://m.example.com') + + # Verify carrier-specific behavior + user_agent = await page.evaluate('() => navigator.userAgent') + print(f'Testing with {carrier}: {user_agent}') + + browser.close() +``` + + + +## Example: Location-based mobile testing + +Combine carrier and location for precise mobile testing: + + + +```typescript Typescript/Javascript +const proxy = await kernel.proxies.create({ + type: 'mobile', + name: 'NYC Verizon Mobile', + config: { + country: 'US', + carrier: 'verizon', + state: 'NY', + city: 'newyork', + zip: '10001' + } +}); + +// Perfect for testing location-based mobile apps +const browser = await kernel.browsers.create({ + proxy_id: proxy.id, + stealth: true // Enhanced stealth for mobile +}); +``` + +```Python Python +proxy = client.proxies.create( + type='mobile', + name='NYC Verizon Mobile', + config={ + 'country': 'US', + 'carrier': 'verizon', + 'state': 'NY', + 'city': 'newyork', + 'zip': '10001' + } +) + +# Perfect for testing location-based mobile apps +browser = client.browsers.create( + proxy_id=proxy.id, + stealth=True # Enhanced stealth for mobile +) +``` + + + +## Benefits + +- Best bot detection avoidance +- Genuine mobile carrier IP addresses +- Carrier-specific testing capabilities +- High trust score from websites + +## Limitations + +- Slowest proxy type +- Higher latency than other options +- Most expensive proxy type +- IP addresses rotate frequently \ No newline at end of file diff --git a/proxies/overview.mdx b/proxies/overview.mdx new file mode 100644 index 0000000..7328933 --- /dev/null +++ b/proxies/overview.mdx @@ -0,0 +1,93 @@ +--- +title: "Proxies Overview" +--- + +import CreateProxySnippet from '/snippets/openapi/post-proxies.mdx'; +import ListProxiesSnippet from '/snippets/openapi/get-proxies.mdx'; +import DeleteProxySnippet from '/snippets/openapi/delete-proxies-id.mdx'; + +Kernel proxies enable you to route browser traffic through different types of proxy servers, providing enhanced privacy, geographic flexibility, and bot detection avoidance. Proxies can be created once and reused across multiple browser sessions. + +## Proxy Types + +Kernel supports five types of proxies, ranked by quality for avoiding bot detection (from best to worst): + +1. **Mobile** - Traffic routed through mobile carrier networks +2. **Residential** - Traffic routed through residential ISP connections +3. **ISP** - Traffic routed through ISP data centers +4. **Datacenter** - Traffic routed through commercial data centers +5. **Custom** - Your own proxy servers + +## 1. Create a proxy + + +First, install the Kernel SDK: +- Typescript/Javascript: `npm install @onkernel/sdk` +- Python: `pip install kernel` + + +Create a proxy configuration that can be reused across browser sessions: + + + +## 2. List your proxies + +View all proxy configurations in your organization: + + + +## 3. Use with browsers + +Once created, you can attach a proxy to any browser session using the `proxy_id` parameter: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +// Create or use existing proxy +const proxy = await kernel.proxies.create({ + type: 'residential', + name: 'US Residential', + config: { + country: 'US' + } +}); + +// Create browser with proxy +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +# Create or use existing proxy +proxy = client.proxies.create( + type='residential', + name='US Residential', + config={ + 'country': 'US' + } +) + +# Create browser with proxy +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## 4. Delete a proxy + +When no longer needed, delete the proxy configuration: + + + + +Deleting a proxy does not affect existing browser sessions that are using it. The proxy configuration is only removed from your organization. + \ No newline at end of file diff --git a/proxies/residential.mdx b/proxies/residential.mdx new file mode 100644 index 0000000..b0d3e6b --- /dev/null +++ b/proxies/residential.mdx @@ -0,0 +1,199 @@ +--- +title: "Residential Proxies" +--- + +Residential proxies route traffic through real residential IP addresses, making them highly effective at avoiding bot detection. They support advanced targeting options including city, state, and operating system. + +## When to use + +- Accessing sites with strong anti-bot protection +- Need to appear as real residential users +- Geographic precision is important +- Willing to trade some speed for better success rates + +## Configuration Options + +Residential proxies support multiple targeting parameters: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'residential', + name: 'California Residential', + config: { + country: 'US', + state: 'CA', + city: 'sanfrancisco', // No spaces in city names + zip: '94102', + os: 'windows', + asn: '7922' // Comcast + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='residential', + name='California Residential', + config={ + 'country': 'US', + 'state': 'CA', + 'city': 'sanfrancisco', # No spaces in city names + 'zip': '94102', + 'os': 'windows', + 'asn': '7922' # Comcast + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Configuration Parameters + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `country` | No* | ISO 3166 country code (required if `city` is provided) | +| `state` | No | Two-letter US state code | +| `city` | No | City name without spaces (e.g., `sanfrancisco`) | +| `zip` | No | US ZIP code | +| `os` | No | Operating system: `windows`, `macos`, or `android` | +| `asn` | No | Autonomous System Number (see [ASN list](https://bgp.potaroo.net/cidr/autnums.html)) | + +## Example: Location-specific scraping + +Target specific geographic locations for localized content: + + + +```typescript Typescript/Javascript +// Create proxies for different cities +const cities = [ + { city: 'newyork', state: 'NY' }, + { city: 'losangeles', state: 'CA' }, + { city: 'chicago', state: 'IL' } +]; + +for (const location of cities) { + const proxy = await kernel.proxies.create({ + type: 'residential', + name: `${location.city} Residential`, + config: { + country: 'US', + state: location.state, + city: location.city + } + }); + + const browser = await kernel.browsers.create({ + proxy_id: proxy.id + }); + + // Access location-specific content + const playwright = await chromium.connectOverCDP(browser.cdp_ws_url); + const context = playwright.contexts()[0]; + const page = context.pages()[0]; + + await page.goto('https://example.com/local-deals'); + // Scrape location-specific data + + await browser.close(); +} +``` + +```Python Python +# Create proxies for different cities +cities = [ + {'city': 'newyork', 'state': 'NY'}, + {'city': 'losangeles', 'state': 'CA'}, + {'city': 'chicago', 'state': 'IL'} +] + +for location in cities: + proxy = client.proxies.create( + type='residential', + name=f"{location['city']} Residential", + config={ + 'country': 'US', + 'state': location['state'], + 'city': location['city'] + } + ) + + browser = client.browsers.create( + proxy_id=proxy.id + ) + + # Access location-specific content + playwright_browser = playwright.chromium.connect_over_cdp(browser.cdp_ws_url) + context = playwright_browser.contexts[0] + page = context.pages[0] + + await page.goto('https://example.com/local-deals') + # Scrape location-specific data + + browser.close() +``` + + + +## Example: OS-specific targeting + +Target specific operating systems for platform-specific content: + + + +```typescript Typescript/Javascript +const proxy = await kernel.proxies.create({ + type: 'residential', + name: 'Windows Residential', + config: { + country: 'US', + os: 'windows' + } +}); + +// Use for Windows-specific sites or apps +``` + +```Python Python +proxy = client.proxies.create( + type='residential', + name='Windows Residential', + config={ + 'country': 'US', + 'os': 'windows' + } +) + +# Use for Windows-specific sites or apps +``` + + + +## Benefits + +- Excellent bot detection avoidance +- Real residential IP addresses +- Fine-grained geographic targeting +- Operating system targeting + +## Limitations + +- Slower than datacenter and ISP proxies +- IP addresses may rotate +- Higher cost than other proxy types \ No newline at end of file From 6e33fe96d9ce7d53683ae0736fda2243dc7fb8e5 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 15:08:42 -0700 Subject: [PATCH 02/12] Rename file --- browsers/{configure-proxy.mdx => proxies.mdx} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename browsers/{configure-proxy.mdx => proxies.mdx} (99%) diff --git a/browsers/configure-proxy.mdx b/browsers/proxies.mdx similarity index 99% rename from browsers/configure-proxy.mdx rename to browsers/proxies.mdx index c5bfb56..23e43a0 100644 --- a/browsers/configure-proxy.mdx +++ b/browsers/proxies.mdx @@ -1,5 +1,5 @@ --- -title: "Configure Proxy" +title: "Proxies" --- Kernel browsers can be configured to route traffic through proxies for enhanced privacy, geographic targeting, and bot detection avoidance. You can either create reusable proxy configurations or use them directly with browsers. @@ -288,4 +288,4 @@ If experiencing slow performance: - [Proxies Overview](/proxies/overview) - Learn about proxy types and capabilities - [Stealth Mode](/browsers/stealth) - Enhance bot detection avoidance -- [Browser Profiles](/browsers/profiles) - Create consistent browser identities \ No newline at end of file +- [Browser Profiles](/browsers/profiles) - Create consistent browser identities From 78d44cdfda80f01eb691a4bbe42e67c4333c3286 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 15:12:55 -0700 Subject: [PATCH 03/12] Simplify proxies doc --- browsers/proxies.mdx | 201 +------------------------------------------ docs.json | 2 +- 2 files changed, 3 insertions(+), 200 deletions(-) diff --git a/browsers/proxies.mdx b/browsers/proxies.mdx index 23e43a0..bc6bbac 100644 --- a/browsers/proxies.mdx +++ b/browsers/proxies.mdx @@ -89,203 +89,6 @@ for i in range(5): -## Best practices - -### 1. Combine with stealth mode - -When using proxies, always enable stealth mode for better bot detection avoidance: - - - -```typescript Typescript/Javascript -const browser = await kernel.browsers.create({ - proxy_id: proxy.id, - stealth: true -}); -``` - -```Python Python -browser = client.browsers.create( - proxy_id=proxy.id, - stealth=True -) -``` - - - -### 2. Match proxy type to use case - -Choose the appropriate proxy type based on your needs: - -- **Mobile**: Best for avoiding detection, slowest -- **Residential**: Great for avoiding detection, moderate speed -- **ISP**: Good balance of speed and detection avoidance -- **Datacenter**: Fastest but most easily detected -- **Custom**: Use your own proxy infrastructure - -### 3. Geographic consistency - -Ensure proxy location matches your browser profile's location: - - - -```typescript Typescript/Javascript -// Create a profile with US location -const profile = await kernel.profiles.create({ - name: 'US User', - locale: 'en-US', - timezone: 'America/New_York' -}); - -// Use a US proxy to match -const proxy = await kernel.proxies.create({ - type: 'residential', - config: { - country: 'US', - state: 'NY' - } -}); - -// Create browser with matching profile and proxy -const browser = await kernel.browsers.create({ - profile_id: profile.id, - proxy_id: proxy.id -}); -``` - -```Python Python -# Create a profile with US location -profile = client.profiles.create( - name='US User', - locale='en-US', - timezone='America/New_York' -) - -# Use a US proxy to match -proxy = client.proxies.create( - type='residential', - config={ - 'country': 'US', - 'state': 'NY' - } -) - -# Create browser with matching profile and proxy -browser = client.browsers.create( - profile_id=profile.id, - proxy_id=proxy.id -) -``` - - - -## Proxy rotation strategies - -### Sequential rotation - -Rotate through proxies in order: - - - -```typescript Typescript/Javascript -const proxies = await kernel.proxies.list(); -let currentIndex = 0; - -function getNextProxy() { - const proxy = proxies[currentIndex]; - currentIndex = (currentIndex + 1) % proxies.length; - return proxy; -} - -// Use different proxy for each task -for (const task of tasks) { - const proxy = getNextProxy(); - const browser = await kernel.browsers.create({ - proxy_id: proxy.id - }); - await performTask(browser, task); - await browser.close(); -} -``` - -```Python Python -proxies = client.proxies.list() -current_index = 0 - -def get_next_proxy(): - global current_index - proxy = proxies[current_index] - current_index = (current_index + 1) % len(proxies) - return proxy - -# Use different proxy for each task -for task in tasks: - proxy = get_next_proxy() - browser = client.browsers.create( - proxy_id=proxy.id - ) - await perform_task(browser, task) - browser.close() -``` - - - -### Random rotation - -Randomly select proxies for better distribution: - - - -```typescript Typescript/Javascript -const proxies = await kernel.proxies.list(); - -function getRandomProxy() { - const index = Math.floor(Math.random() * proxies.length); - return proxies[index]; -} - -const browser = await kernel.browsers.create({ - proxy_id: getRandomProxy().id -}); -``` - -```Python Python -import random - -proxies = client.proxies.list() - -def get_random_proxy(): - return random.choice(proxies) - -browser = client.browsers.create( - proxy_id=get_random_proxy().id -) -``` - - - -## Troubleshooting - -### Proxy connection failures - -If a browser fails to connect through a proxy: - -1. Verify the proxy configuration is correct -2. Check if the proxy type supports your target site -3. Try a different proxy type or location -4. Ensure custom proxies are accessible - -### Performance issues - -If experiencing slow performance: - -1. Consider using faster proxy types (ISP or datacenter) -2. Choose proxy locations closer to target servers -3. Reduce the number of concurrent browsers per proxy -4. Monitor proxy health and rotate out slow proxies - -## Related resources +--- -- [Proxies Overview](/proxies/overview) - Learn about proxy types and capabilities -- [Stealth Mode](/browsers/stealth) - Enhance bot detection avoidance -- [Browser Profiles](/browsers/profiles) - Create consistent browser identities +For more information, see the [Proxies](/proxies/overview) section. \ No newline at end of file diff --git a/docs.json b/docs.json index 0970742..55c1b25 100644 --- a/docs.json +++ b/docs.json @@ -60,7 +60,7 @@ "browsers/standby", "browsers/persistence", "browsers/profiles", - "browsers/configure-proxy", + "browsers/proxies", "browsers/termination", "browsers/file-io", "browsers/live-view", From 98c85273d837fa8047e957430cacccacd5c2173c Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 15:43:35 -0700 Subject: [PATCH 04/12] further simplify --- .gitignore | 5 +- proxies/custom.mdx | 151 ++-------------------------------------- proxies/datacenter.mdx | 69 +----------------- proxies/isp.mdx | 84 +--------------------- proxies/mobile.mdx | 146 +------------------------------------- proxies/residential.mdx | 7 -- 6 files changed, 14 insertions(+), 448 deletions(-) diff --git a/.gitignore b/.gitignore index 3301a1f..fd0fbf6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,7 @@ */.DS_Store .DS_Store -node_modules/ \ No newline at end of file +node_modules/ +venv +__pycache__/** +test.py diff --git a/proxies/custom.mdx b/proxies/custom.mdx index e5cbc97..b717cdd 100644 --- a/proxies/custom.mdx +++ b/proxies/custom.mdx @@ -4,15 +4,13 @@ title: "Custom Proxies" Custom proxies allow you to use your own proxy servers with Kernel browsers. This is useful when you have existing proxy infrastructure or specific proxy requirements not covered by Kernel's managed options. -## When to use - -- You have your own proxy infrastructure -- Need to use specific proxy providers -- Require proxies with special configurations -- Want to use SOCKS5 or HTTP proxies ## Configuration + +Currently, only HTTPS proxies are supported for custom proxy configurations. + + Custom proxies require host, port, and optional authentication: @@ -26,7 +24,7 @@ const proxy = await kernel.proxies.create({ name: 'My Private Proxy', config: { host: 'proxy.example.com', - port: 8080, + port: 443, username: 'user123', password: 'secure_password' } @@ -46,7 +44,7 @@ proxy = client.proxies.create( name='My Private Proxy', config={ 'host': 'proxy.example.com', - 'port': 8080, + 'port': 443, 'username': 'user123', 'password': 'secure_password' } @@ -68,139 +66,4 @@ browser = client.browsers.create( | `username` | No | Username for proxy authentication | | `password` | No* | Password for proxy authentication | -*Note: When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. - -## Example: Using IP-based proxy - - - -```typescript Typescript/Javascript -const proxy = await kernel.proxies.create({ - type: 'custom', - name: 'Direct IP Proxy', - config: { - host: '192.168.1.100', - port: 3128 - } -}); - -const browser = await kernel.browsers.create({ - proxy_id: proxy.id -}); -``` - -```Python Python -proxy = client.proxies.create( - type='custom', - name='Direct IP Proxy', - config={ - 'host': '192.168.1.100', - 'port': 3128 - } -) - -browser = client.browsers.create( - proxy_id=proxy.id -) -``` - - - -## Example: Rotating through multiple custom proxies - - - -```typescript Typescript/Javascript -// List of your proxy servers -const proxyServers = [ - { host: 'proxy1.example.com', port: 8080 }, - { host: 'proxy2.example.com', port: 8080 }, - { host: 'proxy3.example.com', port: 8080 } -]; - -// Create proxy configurations -const proxies = []; -for (const server of proxyServers) { - const proxy = await kernel.proxies.create({ - type: 'custom', - name: `Custom ${server.host}`, - config: { - host: server.host, - port: server.port, - username: 'shared_user', - password: 'shared_pass' - } - }); - proxies.push(proxy); -} - -// Rotate through proxies for different tasks -for (let i = 0; i < tasks.length; i++) { - const proxy = proxies[i % proxies.length]; - const browser = await kernel.browsers.create({ - proxy_id: proxy.id - }); - - // Perform task with this proxy - await performTask(browser); - await browser.close(); -} -``` - -```Python Python -# List of your proxy servers -proxy_servers = [ - {'host': 'proxy1.example.com', 'port': 8080}, - {'host': 'proxy2.example.com', 'port': 8080}, - {'host': 'proxy3.example.com', 'port': 8080} -] - -# Create proxy configurations -proxies = [] -for server in proxy_servers: - proxy = client.proxies.create( - type='custom', - name=f"Custom {server['host']}", - config={ - 'host': server['host'], - 'port': server['port'], - 'username': 'shared_user', - 'password': 'shared_pass' - } - ) - proxies.append(proxy) - -# Rotate through proxies for different tasks -for i, task in enumerate(tasks): - proxy = proxies[i % len(proxies)] - browser = client.browsers.create( - proxy_id=proxy.id - ) - - # Perform task with this proxy - await perform_task(browser) - browser.close() -``` - - - -## Security Considerations - -- Proxy passwords are encrypted and never returned in API responses -- Ensure your proxy servers use secure connections -- Regularly rotate credentials for security -- Monitor proxy usage for unauthorized access - -## Benefits - -- Use existing proxy infrastructure -- Full control over proxy configuration -- Cost-effective if you already have proxies -- Flexibility to use any proxy provider - -## Limitations - -- You're responsible for proxy reliability -- No automatic rotation or failover -- Quality depends on your proxy provider -- Must manage authentication credentials \ No newline at end of file +*Note: When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. \ No newline at end of file diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx index c35759c..8f35e89 100644 --- a/proxies/datacenter.mdx +++ b/proxies/datacenter.mdx @@ -4,13 +4,6 @@ title: "Datacenter Proxies" Datacenter proxies route traffic through commercial data center servers. While they offer the fastest speeds and highest reliability, they are the most easily detected by anti-bot systems. -## When to use - -- High-volume data collection -- Speed is the primary concern -- Target sites have minimal bot detection -- Cost-effective proxy solution needed - ## Configuration Datacenter proxies require only a country specification: @@ -55,64 +48,4 @@ browser = client.browsers.create( ## Supported Countries -Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. - -## Example: Multi-region scraping - -Create multiple datacenter proxies for different regions: - - - -```typescript Typescript/Javascript -const regions = ['US', 'EU', 'JP']; -const proxies = []; - -for (const region of regions) { - const proxy = await kernel.proxies.create({ - type: 'datacenter', - name: `${region} Datacenter`, - config: { - country: region - } - }); - proxies.push(proxy); -} - -// Use different proxies for different tasks -for (const proxy of proxies) { - const browser = await kernel.browsers.create({ - proxy_id: proxy.id - }); - // Perform region-specific tasks - await browser.close(); -} -``` - -```Python Python -regions = ['US', 'EU', 'JP'] -proxies = [] - -for region in regions: - proxy = client.proxies.create( - type='datacenter', - name=f'{region} Datacenter', - config={'country': region} - ) - proxies.append(proxy) - -# Use different proxies for different tasks -for proxy in proxies: - browser = client.browsers.create( - proxy_id=proxy.id - ) - # Perform region-specific tasks - browser.close() -``` - - - -## Limitations - -- Most easily detected by anti-bot systems -- May be blocked by sites with strict bot detection -- IP addresses are from known datacenter ranges \ No newline at end of file +Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. \ No newline at end of file diff --git a/proxies/isp.mdx b/proxies/isp.mdx index f19af17..72df919 100644 --- a/proxies/isp.mdx +++ b/proxies/isp.mdx @@ -4,13 +4,6 @@ title: "ISP Proxies" ISP (Internet Service Provider) proxies combine the speed of datacenter proxies with better legitimacy, as they use IP addresses assigned by real ISPs. They offer a good balance between performance and detection avoidance. -## When to use - -- Need better detection avoidance than datacenter proxies -- Require consistent, static IP addresses -- Speed is still important -- Medium-level bot detection on target sites - ## Configuration ISP proxies require a country specification: @@ -55,79 +48,4 @@ browser = client.browsers.create( ## Supported Countries -Use ISO 3166 country codes (e.g., `US`, `GB`, `DE`) or `EU` for European Union exit nodes. - -## Example: Long-running sessions - -ISP proxies are ideal for maintaining long-running browser sessions: - - - -```typescript Typescript/Javascript -// Create ISP proxy for stable connection -const proxy = await kernel.proxies.create({ - type: 'isp', - name: 'Stable ISP', - config: { - country: 'US' - } -}); - -// Create persistent browser session -const browser = await kernel.browsers.create({ - proxy_id: proxy.id, - persistence: true, - timeout_seconds: 3600 // 1 hour -}); - -// Connect and perform long-running tasks -const playwright = await chromium.connectOverCDP(browser.cdp_ws_url); -const context = playwright.contexts()[0]; -const page = context.pages()[0]; - -// Maintain session for extended operations -await page.goto('https://example.com'); -// ... perform extended operations -``` - -```Python Python -# Create ISP proxy for stable connection -proxy = client.proxies.create( - type='isp', - name='Stable ISP', - config={ - 'country': 'US' - } -) - -# Create persistent browser session -browser = client.browsers.create( - proxy_id=proxy.id, - persistence=True, - timeout_seconds=3600 # 1 hour -) - -# Connect and perform long-running tasks -playwright_browser = playwright.chromium.connect_over_cdp(browser.cdp_ws_url) -context = playwright_browser.contexts[0] -page = context.pages[0] - -# Maintain session for extended operations -await page.goto('https://example.com') -# ... perform extended operations -``` - - - -## Benefits - -- Better than datacenter for avoiding detection -- Static IP addresses for session consistency -- High uptime and reliability -- Good speed performance - -## Limitations - -- More expensive than datacenter proxies -- Still detectable by advanced anti-bot systems -- Limited geographic granularity \ No newline at end of file +Use ISO 3166 country codes (e.g., `US`, `GB`, `DE`) or `EU` for European Union exit nodes. \ No newline at end of file diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx index d6c92bd..9a8a1f4 100644 --- a/proxies/mobile.mdx +++ b/proxies/mobile.mdx @@ -4,13 +4,6 @@ title: "Mobile Proxies" Mobile proxies route traffic through mobile carrier networks, providing the highest level of trust and the best bot detection avoidance. They use IP addresses from real mobile devices on cellular networks. -## When to use - -- Accessing sites with the strongest anti-bot protection -- Mobile app automation and testing -- Need to appear as genuine mobile users -- Success rate is more important than speed - ## Configuration Options Mobile proxies support carrier selection and advanced targeting: @@ -96,141 +89,4 @@ Major carriers worldwide are supported, including: - `airtel` - Bharti Airtel - `telstra` - Telstra -[View all supported carriers in the API reference] - -## Example: Mobile app testing - -Test mobile-specific features across different carriers: - - - -```typescript Typescript/Javascript -const carriers = ['verizon', 'att', 'tmobile']; - -for (const carrier of carriers) { - const proxy = await kernel.proxies.create({ - type: 'mobile', - name: `${carrier} Mobile Test`, - config: { - country: 'US', - carrier: carrier - } - }); - - const browser = await kernel.browsers.create({ - proxy_id: proxy.id, - // Use mobile viewport - viewport: { width: 390, height: 844 } - }); - - const playwright = await chromium.connectOverCDP(browser.cdp_ws_url); - const context = playwright.contexts()[0]; - const page = context.pages()[0]; - - // Test mobile-specific features - await page.goto('https://m.example.com'); - - // Verify carrier-specific behavior - const userAgent = await page.evaluate(() => navigator.userAgent); - console.log(`Testing with ${carrier}: ${userAgent}`); - - await browser.close(); -} -``` - -```Python Python -carriers = ['verizon', 'att', 'tmobile'] - -for carrier in carriers: - proxy = client.proxies.create( - type='mobile', - name=f'{carrier} Mobile Test', - config={ - 'country': 'US', - 'carrier': carrier - } - ) - - browser = client.browsers.create( - proxy_id=proxy.id, - # Use mobile viewport - viewport={'width': 390, 'height': 844} - ) - - playwright_browser = playwright.chromium.connect_over_cdp(browser.cdp_ws_url) - context = playwright_browser.contexts[0] - page = context.pages[0] - - # Test mobile-specific features - await page.goto('https://m.example.com') - - # Verify carrier-specific behavior - user_agent = await page.evaluate('() => navigator.userAgent') - print(f'Testing with {carrier}: {user_agent}') - - browser.close() -``` - - - -## Example: Location-based mobile testing - -Combine carrier and location for precise mobile testing: - - - -```typescript Typescript/Javascript -const proxy = await kernel.proxies.create({ - type: 'mobile', - name: 'NYC Verizon Mobile', - config: { - country: 'US', - carrier: 'verizon', - state: 'NY', - city: 'newyork', - zip: '10001' - } -}); - -// Perfect for testing location-based mobile apps -const browser = await kernel.browsers.create({ - proxy_id: proxy.id, - stealth: true // Enhanced stealth for mobile -}); -``` - -```Python Python -proxy = client.proxies.create( - type='mobile', - name='NYC Verizon Mobile', - config={ - 'country': 'US', - 'carrier': 'verizon', - 'state': 'NY', - 'city': 'newyork', - 'zip': '10001' - } -) - -# Perfect for testing location-based mobile apps -browser = client.browsers.create( - proxy_id=proxy.id, - stealth=True # Enhanced stealth for mobile -) -``` - - - -## Benefits - -- Best bot detection avoidance -- Genuine mobile carrier IP addresses -- Carrier-specific testing capabilities -- High trust score from websites - -## Limitations - -- Slowest proxy type -- Higher latency than other options -- Most expensive proxy type -- IP addresses rotate frequently \ No newline at end of file +[View all supported carriers in the API reference] \ No newline at end of file diff --git a/proxies/residential.mdx b/proxies/residential.mdx index b0d3e6b..f4de6e5 100644 --- a/proxies/residential.mdx +++ b/proxies/residential.mdx @@ -4,13 +4,6 @@ title: "Residential Proxies" Residential proxies route traffic through real residential IP addresses, making them highly effective at avoiding bot detection. They support advanced targeting options including city, state, and operating system. -## When to use - -- Accessing sites with strong anti-bot protection -- Need to appear as real residential users -- Geographic precision is important -- Willing to trade some speed for better success rates - ## Configuration Options Residential proxies support multiple targeting parameters: From f415ff06122683c1a490b97de93962ff5e1fc5eb Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 16:02:16 -0700 Subject: [PATCH 05/12] Clarify configuration parameters --- .gitignore | 1 + proxies/custom.mdx | 20 +++--- proxies/datacenter.mdx | 8 ++- proxies/isp.mdx | 10 ++- proxies/mobile.mdx | 20 +++--- proxies/residential.mdx | 146 +++------------------------------------- 6 files changed, 41 insertions(+), 164 deletions(-) diff --git a/.gitignore b/.gitignore index fd0fbf6..4f8631f 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ node_modules/ venv __pycache__/** test.py +./kernel/** diff --git a/proxies/custom.mdx b/proxies/custom.mdx index b717cdd..62307c9 100644 --- a/proxies/custom.mdx +++ b/proxies/custom.mdx @@ -11,7 +11,13 @@ Custom proxies allow you to use your own proxy servers with Kernel browsers. Thi Currently, only HTTPS proxies are supported for custom proxy configurations. -Custom proxies require host, port, and optional authentication: +| Parameter | Required | Description | +|-----------|----------|-------------| +| `host` | Yes | Proxy server hostname or IP address (max 253 characters) | +| `port` | Yes | Proxy server port (1-65535) | +| `username` | No | Username for proxy authentication (max 128 characters, alphanumeric plus `_`, `-`, `@`, `.`) | +| `password` | No | Password for proxy authentication (5-128 characters, no whitespace or escape characters) | + @@ -57,13 +63,7 @@ browser = client.browsers.create( -## Configuration Parameters -| Parameter | Required | Description | -|-----------|----------|-------------| -| `host` | Yes | Proxy server hostname or IP address | -| `port` | Yes | Proxy server port | -| `username` | No | Username for proxy authentication | -| `password` | No* | Password for proxy authentication | - -*Note: When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. \ No newline at end of file + +When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. + \ No newline at end of file diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx index 8f35e89..bc59f2f 100644 --- a/proxies/datacenter.mdx +++ b/proxies/datacenter.mdx @@ -6,8 +6,6 @@ Datacenter proxies route traffic through commercial data center servers. While t ## Configuration -Datacenter proxies require only a country specification: - ```typescript Typescript/Javascript @@ -46,6 +44,12 @@ browser = client.browsers.create( +## Configuration Parameters + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `country` | Yes | ISO 3166 country code | + ## Supported Countries Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. \ No newline at end of file diff --git a/proxies/isp.mdx b/proxies/isp.mdx index 72df919..308458a 100644 --- a/proxies/isp.mdx +++ b/proxies/isp.mdx @@ -6,8 +6,6 @@ ISP (Internet Service Provider) proxies combine the speed of datacenter proxies ## Configuration -ISP proxies require a country specification: - ```typescript Typescript/Javascript @@ -46,6 +44,12 @@ browser = client.browsers.create( +## Configuration Parameters + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `country` | Yes | ISO 3166 country code | + ## Supported Countries -Use ISO 3166 country codes (e.g., `US`, `GB`, `DE`) or `EU` for European Union exit nodes. \ No newline at end of file +Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. \ No newline at end of file diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx index 9a8a1f4..1b564bb 100644 --- a/proxies/mobile.mdx +++ b/proxies/mobile.mdx @@ -20,10 +20,8 @@ const proxy = await kernel.proxies.create({ config: { country: 'US', carrier: 'verizon', - state: 'CA', city: 'losangeles', - zip: '90001', - asn: '6167' + zip: '90001' } }); @@ -42,10 +40,8 @@ proxy = client.proxies.create( config={ 'country': 'US', 'carrier': 'verizon', - 'state': 'CA', 'city': 'losangeles', - 'zip': '90001', - 'asn': '6167' + 'zip': '90001' } ) @@ -60,12 +56,12 @@ browser = client.browsers.create( | Parameter | Required | Description | |-----------|----------|-------------| -| `country` | No* | ISO 3166 country code (required if `city` is provided) | -| `carrier` | No | Mobile carrier name (see supported carriers below) | -| `state` | No | Two-letter US state code | -| `city` | No | City name without spaces | -| `zip` | No | US ZIP code | -| `asn` | No | Autonomous System Number | +| `country` | No | ISO 3166 country code (e.g., `US`, `GB`) | +| `carrier` | No | Mobile carrier name (e.g., `verizon`, `att`) | +| `state` | No | Two-letter state code (e.g., `NY`, `CA`). Only supported for US and Australia. **Cannot be used with `city`**. | +| `city` | No | City name (lowercase letters only, no spaces, e.g., `newyork`, `losangeles`). Required if `zip` is provided. | +| `zip` | No | US ZIP code (5 digits only, e.g., `10001`). **Requires `city` to be provided**. | +| `asn` | No | Autonomous System Number (e.g., `AS15169`, `15169`). **Mutually exclusive with geo-location targeting** (`country`, `city`, `state`, `zip`). | ## Supported Carriers diff --git a/proxies/residential.mdx b/proxies/residential.mdx index f4de6e5..b6e56b5 100644 --- a/proxies/residential.mdx +++ b/proxies/residential.mdx @@ -19,11 +19,9 @@ const proxy = await kernel.proxies.create({ name: 'California Residential', config: { country: 'US', - state: 'CA', - city: 'sanfrancisco', // No spaces in city names + city: 'sanfrancisco', zip: '94102', - os: 'windows', - asn: '7922' // Comcast + os: 'windows' } }); @@ -41,11 +39,9 @@ proxy = client.proxies.create( name='California Residential', config={ 'country': 'US', - 'state': 'CA', - 'city': 'sanfrancisco', # No spaces in city names + 'city': 'sanfrancisco', 'zip': '94102', - 'os': 'windows', - 'asn': '7922' # Comcast + 'os': 'windows' } ) @@ -60,133 +56,9 @@ browser = client.browsers.create( | Parameter | Required | Description | |-----------|----------|-------------| -| `country` | No* | ISO 3166 country code (required if `city` is provided) | -| `state` | No | Two-letter US state code | -| `city` | No | City name without spaces (e.g., `sanfrancisco`) | -| `zip` | No | US ZIP code | +| `country` | No | ISO 3166 country code (e.g., `US`, `GB`) | +| `state` | No | Two-letter state code (e.g., `NY`, `CA`). Only supported for US and Australia. **Cannot be used with `city`**. | +| `city` | No | City name (lowercase letters only, no spaces, e.g., `sanfrancisco`, `newyork`). Required if `zip` is provided. | +| `zip` | No | US ZIP code (5 digits only, e.g., `94102`). **Requires `city` to be provided**. | | `os` | No | Operating system: `windows`, `macos`, or `android` | -| `asn` | No | Autonomous System Number (see [ASN list](https://bgp.potaroo.net/cidr/autnums.html)) | - -## Example: Location-specific scraping - -Target specific geographic locations for localized content: - - - -```typescript Typescript/Javascript -// Create proxies for different cities -const cities = [ - { city: 'newyork', state: 'NY' }, - { city: 'losangeles', state: 'CA' }, - { city: 'chicago', state: 'IL' } -]; - -for (const location of cities) { - const proxy = await kernel.proxies.create({ - type: 'residential', - name: `${location.city} Residential`, - config: { - country: 'US', - state: location.state, - city: location.city - } - }); - - const browser = await kernel.browsers.create({ - proxy_id: proxy.id - }); - - // Access location-specific content - const playwright = await chromium.connectOverCDP(browser.cdp_ws_url); - const context = playwright.contexts()[0]; - const page = context.pages()[0]; - - await page.goto('https://example.com/local-deals'); - // Scrape location-specific data - - await browser.close(); -} -``` - -```Python Python -# Create proxies for different cities -cities = [ - {'city': 'newyork', 'state': 'NY'}, - {'city': 'losangeles', 'state': 'CA'}, - {'city': 'chicago', 'state': 'IL'} -] - -for location in cities: - proxy = client.proxies.create( - type='residential', - name=f"{location['city']} Residential", - config={ - 'country': 'US', - 'state': location['state'], - 'city': location['city'] - } - ) - - browser = client.browsers.create( - proxy_id=proxy.id - ) - - # Access location-specific content - playwright_browser = playwright.chromium.connect_over_cdp(browser.cdp_ws_url) - context = playwright_browser.contexts[0] - page = context.pages[0] - - await page.goto('https://example.com/local-deals') - # Scrape location-specific data - - browser.close() -``` - - - -## Example: OS-specific targeting - -Target specific operating systems for platform-specific content: - - - -```typescript Typescript/Javascript -const proxy = await kernel.proxies.create({ - type: 'residential', - name: 'Windows Residential', - config: { - country: 'US', - os: 'windows' - } -}); - -// Use for Windows-specific sites or apps -``` - -```Python Python -proxy = client.proxies.create( - type='residential', - name='Windows Residential', - config={ - 'country': 'US', - 'os': 'windows' - } -) - -# Use for Windows-specific sites or apps -``` - - - -## Benefits - -- Excellent bot detection avoidance -- Real residential IP addresses -- Fine-grained geographic targeting -- Operating system targeting - -## Limitations - -- Slower than datacenter and ISP proxies -- IP addresses may rotate -- Higher cost than other proxy types \ No newline at end of file +| `asn` | No | Autonomous System Number (e.g., `AS7922`, `7922`). **Mutually exclusive with geo-location targeting** (`country`, `city`, `state`, `zip`). | \ No newline at end of file From 88531d7d2e180ccb5f1df13fe1e6d8954cb67ac2 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 16:08:09 -0700 Subject: [PATCH 06/12] Clean up docs --- proxies/custom.mdx | 15 +++++++-------- proxies/datacenter.mdx | 10 +++------- proxies/isp.mdx | 10 +++------- proxies/mobile.mdx | 18 ++++++++---------- proxies/residential.mdx | 16 +++++++--------- 5 files changed, 28 insertions(+), 41 deletions(-) diff --git a/proxies/custom.mdx b/proxies/custom.mdx index 62307c9..2913419 100644 --- a/proxies/custom.mdx +++ b/proxies/custom.mdx @@ -4,20 +4,13 @@ title: "Custom Proxies" Custom proxies allow you to use your own proxy servers with Kernel browsers. This is useful when you have existing proxy infrastructure or specific proxy requirements not covered by Kernel's managed options. - ## Configuration Currently, only HTTPS proxies are supported for custom proxy configurations. -| Parameter | Required | Description | -|-----------|----------|-------------| -| `host` | Yes | Proxy server hostname or IP address (max 253 characters) | -| `port` | Yes | Proxy server port (1-65535) | -| `username` | No | Username for proxy authentication (max 128 characters, alphanumeric plus `_`, `-`, `@`, `.`) | -| `password` | No | Password for proxy authentication (5-128 characters, no whitespace or escape characters) | - +Specify the host, port, and optional authentication credentials for your proxy server: @@ -63,6 +56,12 @@ browser = client.browsers.create( +## Configuration Parameters + +- **`host`** (required) - Proxy server hostname or IP address +- **`port`** (required) - Proxy server port (1-65535) +- **`username`** - Username for proxy authentication +- **`password`** - Password for proxy authentication (minimum 5 characters) When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx index bc59f2f..7339250 100644 --- a/proxies/datacenter.mdx +++ b/proxies/datacenter.mdx @@ -6,6 +6,8 @@ Datacenter proxies route traffic through commercial data center servers. While t ## Configuration +Datacenter proxies require a country to route traffic through: + ```typescript Typescript/Javascript @@ -46,10 +48,4 @@ browser = client.browsers.create( ## Configuration Parameters -| Parameter | Required | Description | -|-----------|----------|-------------| -| `country` | Yes | ISO 3166 country code | - -## Supported Countries - -Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. \ No newline at end of file +- **`country`** (required) - ISO 3166 country code (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes \ No newline at end of file diff --git a/proxies/isp.mdx b/proxies/isp.mdx index 308458a..2c2912f 100644 --- a/proxies/isp.mdx +++ b/proxies/isp.mdx @@ -6,6 +6,8 @@ ISP (Internet Service Provider) proxies combine the speed of datacenter proxies ## Configuration +ISP proxies require a country to route traffic through: + ```typescript Typescript/Javascript @@ -46,10 +48,4 @@ browser = client.browsers.create( ## Configuration Parameters -| Parameter | Required | Description | -|-----------|----------|-------------| -| `country` | Yes | ISO 3166 country code | - -## Supported Countries - -Use ISO 3166 country codes (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes. \ No newline at end of file +- **`country`** (required) - ISO 3166 country code (e.g., `US`, `GB`, `DE`) or `EU` for European Union exit nodes \ No newline at end of file diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx index 1b564bb..07be5e7 100644 --- a/proxies/mobile.mdx +++ b/proxies/mobile.mdx @@ -4,9 +4,9 @@ title: "Mobile Proxies" Mobile proxies route traffic through mobile carrier networks, providing the highest level of trust and the best bot detection avoidance. They use IP addresses from real mobile devices on cellular networks. -## Configuration Options +## Configuration -Mobile proxies support carrier selection and advanced targeting: +Mobile proxies support carrier selection and advanced targeting options: @@ -54,14 +54,12 @@ browser = client.browsers.create( ## Configuration Parameters -| Parameter | Required | Description | -|-----------|----------|-------------| -| `country` | No | ISO 3166 country code (e.g., `US`, `GB`) | -| `carrier` | No | Mobile carrier name (e.g., `verizon`, `att`) | -| `state` | No | Two-letter state code (e.g., `NY`, `CA`). Only supported for US and Australia. **Cannot be used with `city`**. | -| `city` | No | City name (lowercase letters only, no spaces, e.g., `newyork`, `losangeles`). Required if `zip` is provided. | -| `zip` | No | US ZIP code (5 digits only, e.g., `10001`). **Requires `city` to be provided**. | -| `asn` | No | Autonomous System Number (e.g., `AS15169`, `15169`). **Mutually exclusive with geo-location targeting** (`country`, `city`, `state`, `zip`). | +- **`country`** - ISO 3166 country code +- **`carrier`** - Mobile carrier name (e.g., `verizon`, `att`, `tmobile`) +- **`state`** - Two-letter state code. Only supported for US and Australia. Cannot be used with `city` +- **`city`** - City name (lowercase, no spaces, e.g., `newyork`, `losangeles`). Required if `zip` is provided +- **`zip`** - US ZIP code (5 digits). Requires `city` to be provided +- **`asn`** - Autonomous System Number. Mutually exclusive with geo-location targeting ## Supported Carriers diff --git a/proxies/residential.mdx b/proxies/residential.mdx index b6e56b5..1a22cce 100644 --- a/proxies/residential.mdx +++ b/proxies/residential.mdx @@ -4,7 +4,7 @@ title: "Residential Proxies" Residential proxies route traffic through real residential IP addresses, making them highly effective at avoiding bot detection. They support advanced targeting options including city, state, and operating system. -## Configuration Options +## Configuration Residential proxies support multiple targeting parameters: @@ -54,11 +54,9 @@ browser = client.browsers.create( ## Configuration Parameters -| Parameter | Required | Description | -|-----------|----------|-------------| -| `country` | No | ISO 3166 country code (e.g., `US`, `GB`) | -| `state` | No | Two-letter state code (e.g., `NY`, `CA`). Only supported for US and Australia. **Cannot be used with `city`**. | -| `city` | No | City name (lowercase letters only, no spaces, e.g., `sanfrancisco`, `newyork`). Required if `zip` is provided. | -| `zip` | No | US ZIP code (5 digits only, e.g., `94102`). **Requires `city` to be provided**. | -| `os` | No | Operating system: `windows`, `macos`, or `android` | -| `asn` | No | Autonomous System Number (e.g., `AS7922`, `7922`). **Mutually exclusive with geo-location targeting** (`country`, `city`, `state`, `zip`). | \ No newline at end of file +- **`country`** - ISO 3166 country code +- **`state`** - Two-letter state code. Only supported for US and Australia. Cannot be used with `city` +- **`city`** - City name (lowercase, no spaces, e.g., `sanfrancisco`, `newyork`). Required if `zip` is provided +- **`zip`** - US ZIP code (5 digits). Requires `city` to be provided +- **`os`** - Operating system: `windows`, `macos`, or `android` +- **`asn`** - Autonomous System Number. Mutually exclusive with geo-location targeting \ No newline at end of file From 6c4efc9d9af04da6da9a53234463635bdf270bbb Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 16:25:54 -0700 Subject: [PATCH 07/12] Fix ISP doc --- proxies/isp.mdx | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/proxies/isp.mdx b/proxies/isp.mdx index 2c2912f..594048a 100644 --- a/proxies/isp.mdx +++ b/proxies/isp.mdx @@ -2,11 +2,11 @@ title: "ISP Proxies" --- -ISP (Internet Service Provider) proxies combine the speed of datacenter proxies with better legitimacy, as they use IP addresses assigned by real ISPs. They offer a good balance between performance and detection avoidance. +ISP proxies use residential IP addresses hosted on high-speed servers, purchased or leased from Internet Service Providers for commercial use. Target sites classify them as residential IPs, allowing you to access websites like a real user while maintaining the speed and reliability of datacenter infrastructure. They're ideal when datacenter proxies are blocked but you still need fast, cost-effective proxies. ## Configuration -ISP proxies require a country to route traffic through: +Create an ISP proxy with optional targeting: @@ -16,10 +16,7 @@ const kernel = new Kernel(); const proxy = await kernel.proxies.create({ type: 'isp', - name: 'US ISP Proxy', - config: { - country: 'US' - } + name: 'My ISP Proxy' }); const browser = await kernel.browsers.create({ @@ -33,10 +30,7 @@ client = kernel.Kernel() proxy = client.proxies.create( type='isp', - name='US ISP Proxy', - config={ - 'country': 'US' - } + name='My ISP Proxy' ) browser = client.browsers.create( @@ -48,4 +42,4 @@ browser = client.browsers.create( ## Configuration Parameters -- **`country`** (required) - ISO 3166 country code (e.g., `US`, `GB`, `DE`) or `EU` for European Union exit nodes \ No newline at end of file +- **`country`** (required) - ISO 3166 country code. Not many countries are supported for ISP proxies, try to create a proxy in a country to check if it's available. \ No newline at end of file From 9b33dae20897403bbf5b8efe369a811487015e9a Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 16:27:02 -0700 Subject: [PATCH 08/12] Update intro datacenter --- proxies/datacenter.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx index 7339250..547b914 100644 --- a/proxies/datacenter.mdx +++ b/proxies/datacenter.mdx @@ -2,7 +2,7 @@ title: "Datacenter Proxies" --- -Datacenter proxies route traffic through commercial data center servers. While they offer the fastest speeds and highest reliability, they are the most easily detected by anti-bot systems. +Datacenter proxies use IP addresses assigned from datacenter servers to route your traffic and access locations around the world. With a shorter journey and simplified architecture, datacenter proxies are both the fastest and most cost-effective proxy option. They're best for accessing websites without sophisticated blocking methods. ## Configuration From e161fddfabd364dcee6bcf260b621611922720a9 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 16:27:52 -0700 Subject: [PATCH 09/12] Update mobile intro --- proxies/mobile.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx index 07be5e7..7c6cfa0 100644 --- a/proxies/mobile.mdx +++ b/proxies/mobile.mdx @@ -2,7 +2,7 @@ title: "Mobile Proxies" --- -Mobile proxies route traffic through mobile carrier networks, providing the highest level of trust and the best bot detection avoidance. They use IP addresses from real mobile devices on cellular networks. +Mobile proxies use real mobile IPs from devices on cellular networks worldwide. These IPs are distributed by ISPs to mobile devices, where real users opt-in to share their connection. Mobile proxies let you connect through 3G/4G mobile connections in every country and city, accessing the internet as a real mobile user would, with complete ASN, carrier, and mobile network targeting capabilities. ## Configuration @@ -81,6 +81,4 @@ Major carriers worldwide are supported, including: - `docomo` - NTT Docomo - `chinamobile` - China Mobile - `airtel` - Bharti Airtel -- `telstra` - Telstra - -[View all supported carriers in the API reference] \ No newline at end of file +- `telstra` - Telstra \ No newline at end of file From bb947fff7633e2487df37579c25fa068b60298d2 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 29 Sep 2025 16:28:44 -0700 Subject: [PATCH 10/12] Update residential intro --- proxies/residential.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proxies/residential.mdx b/proxies/residential.mdx index 1a22cce..016a42f 100644 --- a/proxies/residential.mdx +++ b/proxies/residential.mdx @@ -2,7 +2,7 @@ title: "Residential Proxies" --- -Residential proxies route traffic through real residential IP addresses, making them highly effective at avoiding bot detection. They support advanced targeting options including city, state, and operating system. +Residential proxies use real IPs from people who opt-in and are rewarded for lending their IP to the network. This allows you to target sophisticated, hard-to-reach websites with local IPs from the target area, helping you browse or collect data as a real person would. They're ideal when datacenter or ISP proxies result in low success rates or get blocked. ## Configuration From e8d8e6e8ce151fc5c2d41a43455fcf6874b6ff06 Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Tue, 30 Sep 2025 09:50:40 -0700 Subject: [PATCH 11/12] IA proxies (#59) * IA proxies * Reorder --- browsers/proxies.mdx | 94 ----------------------------------------- browsers/stealth.mdx | 8 ++-- docs.json | 32 ++++++++------ proxies/custom.mdx | 8 ++-- proxies/isp.mdx | 2 +- proxies/mobile.mdx | 8 ++-- proxies/overview.mdx | 30 ++++++------- proxies/residential.mdx | 2 +- 8 files changed, 44 insertions(+), 140 deletions(-) delete mode 100644 browsers/proxies.mdx diff --git a/browsers/proxies.mdx b/browsers/proxies.mdx deleted file mode 100644 index bc6bbac..0000000 --- a/browsers/proxies.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "Proxies" ---- - -Kernel browsers can be configured to route traffic through proxies for enhanced privacy, geographic targeting, and bot detection avoidance. You can either create reusable proxy configurations or use them directly with browsers. - -## Using proxies with browsers - -To use a proxy with a browser, specify the `proxy_id` parameter when creating the browser session: - - - -```typescript Typescript/Javascript -import { Kernel } from '@onkernel/sdk'; -const kernel = new Kernel(); - -// First, create a proxy configuration -const proxy = await kernel.proxies.create({ - type: 'residential', - name: 'US Residential', - config: { - country: 'US' - } -}); - -// Then use it with a browser -const browser = await kernel.browsers.create({ - proxy_id: proxy.id, - stealth: true // Recommended when using proxies -}); -``` - -```Python Python -import kernel -client = kernel.Kernel() - -# First, create a proxy configuration -proxy = client.proxies.create( - type='residential', - name='US Residential', - config={ - 'country': 'US' - } -) - -# Then use it with a browser -browser = client.browsers.create( - proxy_id=proxy.id, - stealth=True # Recommended when using proxies -) -``` - - - -## Reusing proxy configurations - -Once created, proxy configurations can be reused across multiple browser sessions: - - - -```typescript Typescript/Javascript -// Get existing proxies -const proxies = await kernel.proxies.list(); -const usProxy = proxies.find(p => p.name === 'US Residential'); - -// Create multiple browsers with the same proxy -const browsers = []; -for (let i = 0; i < 5; i++) { - const browser = await kernel.browsers.create({ - proxy_id: usProxy.id - }); - browsers.push(browser); -} -``` - -```Python Python -# Get existing proxies -proxies = client.proxies.list() -us_proxy = next(p for p in proxies if p.name == 'US Residential') - -# Create multiple browsers with the same proxy -browsers = [] -for i in range(5): - browser = client.browsers.create( - proxy_id=us_proxy.id - ) - browsers.append(browser) -``` - - - ---- - -For more information, see the [Proxies](/proxies/overview) section. \ No newline at end of file diff --git a/browsers/stealth.mdx b/browsers/stealth.mdx index ebb2aea..b7cef53 100644 --- a/browsers/stealth.mdx +++ b/browsers/stealth.mdx @@ -2,9 +2,9 @@ title: "Stealth Mode" --- -Kernel browsers can be configured to `stealth` mode, which adds a high performant residential proxy and auto-CAPTCHA solver to your instances. +Kernel browsers can be configured to `stealth` mode, which adds our recommended proxy configuration to your browser instances. It also adds a `reCAPTCHA solver` to the browser, so it automatically solves [reCAPTCHAs](https://www.google.com/recaptcha/api2/demo) on your behalf. -To turn on stealth mode, set its flag in your app code when instantiating Kernel: +To turn on stealth mode, set its flag when instantiating Kernel browsers: ```typescript Typescript/Javascript @@ -23,4 +23,6 @@ kernel_browser = client.browsers.create(invocation_id=ctx.invocation_id, stealth [Anthropic Computer Use](/quickstart#sample-apps-reference) stops when it runs into a CAPTCHA. Use Kernel's auto-captcha solver by adding this to your prompt: `"If you see a CAPTCHA or similar test, just wait for it to get solved automatically by the browser."` - \ No newline at end of file + + +If you're looking for proxy-level configuration with Kernel browsers, see [Proxies](/proxies/overview). diff --git a/docs.json b/docs.json index 55c1b25..b7c0b19 100644 --- a/docs.json +++ b/docs.json @@ -56,26 +56,30 @@ "pages": [ "browsers/create-a-browser", "browsers/headless", - "browsers/stealth", "browsers/standby", "browsers/persistence", "browsers/profiles", - "browsers/proxies", "browsers/termination", "browsers/file-io", "browsers/live-view", - "browsers/replays" - ] - }, - { - "group": "Proxies", - "pages": [ - "proxies/overview", - "proxies/datacenter", - "proxies/isp", - "proxies/residential", - "proxies/mobile", - "proxies/custom" + "browsers/replays", + { + "group": "Bot Anti-Detection", + "pages": [ + "browsers/stealth", + { + "group": "Proxies", + "pages": [ + "proxies/overview", + "proxies/custom", + "proxies/mobile", + "proxies/residential", + "proxies/isp", + "proxies/datacenter" + ] + } + ] + } ] }, { diff --git a/proxies/custom.mdx b/proxies/custom.mdx index 2913419..d4e204d 100644 --- a/proxies/custom.mdx +++ b/proxies/custom.mdx @@ -6,9 +6,9 @@ Custom proxies allow you to use your own proxy servers with Kernel browsers. Thi ## Configuration - + Currently, only HTTPS proxies are supported for custom proxy configurations. - + Specify the host, port, and optional authentication credentials for your proxy server: @@ -63,6 +63,6 @@ browser = client.browsers.create( - **`username`** - Username for proxy authentication - **`password`** - Password for proxy authentication (minimum 5 characters) - + When creating a proxy with authentication, provide the password. The API response will only indicate if a password exists (`has_password: true`) but won't return the actual password for security reasons. - \ No newline at end of file + \ No newline at end of file diff --git a/proxies/isp.mdx b/proxies/isp.mdx index 2c2912f..5670d6d 100644 --- a/proxies/isp.mdx +++ b/proxies/isp.mdx @@ -2,7 +2,7 @@ title: "ISP Proxies" --- -ISP (Internet Service Provider) proxies combine the speed of datacenter proxies with better legitimacy, as they use IP addresses assigned by real ISPs. They offer a good balance between performance and detection avoidance. +ISP (Internet Service Provider) proxies combine the speed of datacenter proxies with better legitimacy, as they use IP addresses assigned by real ISPs. ## Configuration diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx index 07be5e7..d7ab95a 100644 --- a/proxies/mobile.mdx +++ b/proxies/mobile.mdx @@ -55,7 +55,7 @@ browser = client.browsers.create( ## Configuration Parameters - **`country`** - ISO 3166 country code -- **`carrier`** - Mobile carrier name (e.g., `verizon`, `att`, `tmobile`) +- **`carrier`** - Mobile carrier name (see available carriers below) - **`state`** - Two-letter state code. Only supported for US and Australia. Cannot be used with `city` - **`city`** - City name (lowercase, no spaces, e.g., `newyork`, `losangeles`). Required if `zip` is provided - **`zip`** - US ZIP code (5 digits). Requires `city` to be provided @@ -63,7 +63,7 @@ browser = client.browsers.create( ## Supported Carriers -Major carriers worldwide are supported, including: +Major carriers worldwide are supported: **US Carriers:** - `att` - AT&T @@ -81,6 +81,4 @@ Major carriers worldwide are supported, including: - `docomo` - NTT Docomo - `chinamobile` - China Mobile - `airtel` - Bharti Airtel -- `telstra` - Telstra - -[View all supported carriers in the API reference] \ No newline at end of file +- `telstra` - Telstra \ No newline at end of file diff --git a/proxies/overview.mdx b/proxies/overview.mdx index 7328933..c5bded9 100644 --- a/proxies/overview.mdx +++ b/proxies/overview.mdx @@ -1,32 +1,26 @@ --- -title: "Proxies Overview" +title: "Overview" --- import CreateProxySnippet from '/snippets/openapi/post-proxies.mdx'; import ListProxiesSnippet from '/snippets/openapi/get-proxies.mdx'; import DeleteProxySnippet from '/snippets/openapi/delete-proxies-id.mdx'; -Kernel proxies enable you to route browser traffic through different types of proxy servers, providing enhanced privacy, geographic flexibility, and bot detection avoidance. Proxies can be created once and reused across multiple browser sessions. +Kernel proxies enable you to route browser traffic through different types of proxy servers, providing enhanced privacy, flexibility, and bot detection avoidance. Proxies can be created once and reused across multiple browser sessions. ## Proxy Types -Kernel supports five types of proxies, ranked by quality for avoiding bot detection (from best to worst): +Kernel supports five types of proxies, ranked by quality (from best to worst): -1. **Mobile** - Traffic routed through mobile carrier networks -2. **Residential** - Traffic routed through residential ISP connections -3. **ISP** - Traffic routed through ISP data centers -4. **Datacenter** - Traffic routed through commercial data centers -5. **Custom** - Your own proxy servers +0. [**Custom**](/proxies/custom) - Your own proxy servers +1. [**Mobile**](/proxies/mobile) - Traffic routed through mobile carrier networks +2. [**Residential**](/proxies/residential) - Traffic routed through residential ISP connections +3. [**ISP**](/proxies/isp) - Traffic routed through ISP data centers +4. [**Datacenter**](/proxies/datacenter) - Traffic routed through commercial data centers ## 1. Create a proxy - -First, install the Kernel SDK: -- Typescript/Javascript: `npm install @onkernel/sdk` -- Python: `pip install kernel` - - -Create a proxy configuration that can be reused across browser sessions: +Create a proxy configuration from the types above that can be reused across browser sessions: @@ -88,6 +82,6 @@ When no longer needed, delete the proxy configuration: - -Deleting a proxy does not affect existing browser sessions that are using it. The proxy configuration is only removed from your organization. - \ No newline at end of file + +Deleting a proxy does not affect existing browser sessions that are currently using it. The configuration is only removed from your organization so it can't be used in future browser sessions. + \ No newline at end of file diff --git a/proxies/residential.mdx b/proxies/residential.mdx index 1a22cce..c8686d4 100644 --- a/proxies/residential.mdx +++ b/proxies/residential.mdx @@ -2,7 +2,7 @@ title: "Residential Proxies" --- -Residential proxies route traffic through real residential IP addresses, making them highly effective at avoiding bot detection. They support advanced targeting options including city, state, and operating system. +Residential proxies route traffic through real residential IP addresses. They support advanced targeting options including city, state, and operating system. ## Configuration From 5897ebd88db89be90aa22d63b220a07ba03ca82a Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Tue, 30 Sep 2025 10:03:30 -0700 Subject: [PATCH 12/12] Document known limitations --- proxies/datacenter.mdx | 2 +- proxies/mobile.mdx | 22 ++++++++++++---------- proxies/overview.mdx | 9 ++++++++- 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx index 547b914..7c0aaac 100644 --- a/proxies/datacenter.mdx +++ b/proxies/datacenter.mdx @@ -2,7 +2,7 @@ title: "Datacenter Proxies" --- -Datacenter proxies use IP addresses assigned from datacenter servers to route your traffic and access locations around the world. With a shorter journey and simplified architecture, datacenter proxies are both the fastest and most cost-effective proxy option. They're best for accessing websites without sophisticated blocking methods. +Datacenter proxies use IP addresses assigned from datacenter servers to route your traffic and access locations around the world. With a shorter journey and simplified architecture, datacenter proxies are both the fastest and most cost-effective proxy option. ## Configuration diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx index 1164a48..bd60631 100644 --- a/proxies/mobile.mdx +++ b/proxies/mobile.mdx @@ -2,7 +2,7 @@ title: "Mobile Proxies" --- -Mobile proxies use real mobile IPs from devices on cellular networks worldwide. These IPs are distributed by ISPs to mobile devices, where real users opt-in to share their connection. Mobile proxies let you connect through 3G/4G mobile connections in every country and city, accessing the internet as a real mobile user would, with complete ASN, carrier, and mobile network targeting capabilities. +Mobile proxies use real mobile IPs from devices on cellular networks worldwide. These IPs are distributed by ISPs to mobile devices, where real users opt-in to share their connection. ## Configuration @@ -16,12 +16,10 @@ const kernel = new Kernel(); const proxy = await kernel.proxies.create({ type: 'mobile', - name: 'Verizon Mobile', + name: 'LA Mobile', config: { country: 'US', - carrier: 'verizon', - city: 'losangeles', - zip: '90001' + city: 'losangeles' } }); @@ -36,12 +34,10 @@ client = kernel.Kernel() proxy = client.proxies.create( type='mobile', - name='Verizon Mobile', + name='LA Mobile', config={ 'country': 'US', - 'carrier': 'verizon', - 'city': 'losangeles', - 'zip': '90001' + 'city': 'losangeles' } ) @@ -81,4 +77,10 @@ Major carriers worldwide are supported: - `docomo` - NTT Docomo - `chinamobile` - China Mobile - `airtel` - Bharti Airtel -- `telstra` - Telstra \ No newline at end of file +- `telstra` - Telstra + +See API reference for complete list of carriers. + +## Limitations + +Highly specific geotargeting may not have available IP addresses. Try creating a mobile proxy configuration to see if a specific geotargeting combination is available. Use less specific geotargeting where not available, or use residential proxies which are the most flexible option. \ No newline at end of file diff --git a/proxies/overview.mdx b/proxies/overview.mdx index c5bded9..b280ded 100644 --- a/proxies/overview.mdx +++ b/proxies/overview.mdx @@ -84,4 +84,11 @@ When no longer needed, delete the proxy configuration: Deleting a proxy does not affect existing browser sessions that are currently using it. The configuration is only removed from your organization so it can't be used in future browser sessions. - \ No newline at end of file + + +## Limitations + +Some sites are blocked by the proxy network: +- Government websites +- Google +- LinkedIn \ No newline at end of file