diff --git a/.gitignore b/.gitignore index 3301a1f..4f8631f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,8 @@ */.DS_Store .DS_Store -node_modules/ \ No newline at end of file +node_modules/ +venv +__pycache__/** +test.py +./kernel/** 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 c0385d1..b7c0b19 100644 --- a/docs.json +++ b/docs.json @@ -56,14 +56,30 @@ "pages": [ "browsers/create-a-browser", "browsers/headless", - "browsers/stealth", "browsers/standby", "browsers/persistence", "browsers/profiles", "browsers/termination", "browsers/file-io", "browsers/live-view", - "browsers/replays" + "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 new file mode 100644 index 0000000..d4e204d --- /dev/null +++ b/proxies/custom.mdx @@ -0,0 +1,68 @@ +--- +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. + + +Specify the host, port, and optional authentication credentials for your proxy server: + + + +```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: 443, + 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': 443, + 'username': 'user123', + 'password': 'secure_password' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## 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. + \ No newline at end of file diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx new file mode 100644 index 0000000..7c0aaac --- /dev/null +++ b/proxies/datacenter.mdx @@ -0,0 +1,51 @@ +--- +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. + +## Configuration + +Datacenter proxies require a country to route traffic through: + + + +```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 +) +``` + + + +## Configuration Parameters + +- **`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 new file mode 100644 index 0000000..7164aba --- /dev/null +++ b/proxies/isp.mdx @@ -0,0 +1,45 @@ +--- +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. + +## Configuration + +Create an ISP proxy with optional targeting: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'isp', + name: 'My ISP Proxy' +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='isp', + name='My ISP Proxy' +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Configuration Parameters + +- **`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 diff --git a/proxies/mobile.mdx b/proxies/mobile.mdx new file mode 100644 index 0000000..bd60631 --- /dev/null +++ b/proxies/mobile.mdx @@ -0,0 +1,86 @@ +--- +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. + +## Configuration + +Mobile proxies support carrier selection and advanced targeting options: + + + +```typescript Typescript/Javascript +import { Kernel } from '@onkernel/sdk'; +const kernel = new Kernel(); + +const proxy = await kernel.proxies.create({ + type: 'mobile', + name: 'LA Mobile', + config: { + country: 'US', + city: 'losangeles' + } +}); + +const browser = await kernel.browsers.create({ + proxy_id: proxy.id +}); +``` + +```Python Python +import kernel +client = kernel.Kernel() + +proxy = client.proxies.create( + type='mobile', + name='LA Mobile', + config={ + 'country': 'US', + 'city': 'losangeles' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Configuration Parameters + +- **`country`** - ISO 3166 country code +- **`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 +- **`asn`** - Autonomous System Number. Mutually exclusive with geo-location targeting + +## Supported Carriers + +Major carriers worldwide are supported: + +**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 + +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 new file mode 100644 index 0000000..b280ded --- /dev/null +++ b/proxies/overview.mdx @@ -0,0 +1,94 @@ +--- +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, 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 (from best to worst): + +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 + +Create a proxy configuration from the types above 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 currently using it. The configuration is only removed from your organization so it can't be used in future browser sessions. + + +## Limitations + +Some sites are blocked by the proxy network: +- Government websites +- Google +- LinkedIn \ No newline at end of file diff --git a/proxies/residential.mdx b/proxies/residential.mdx new file mode 100644 index 0000000..c8686d4 --- /dev/null +++ b/proxies/residential.mdx @@ -0,0 +1,62 @@ +--- +title: "Residential Proxies" +--- + +Residential proxies route traffic through real residential IP addresses. They support advanced targeting options including city, state, and operating system. + +## Configuration + +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', + city: 'sanfrancisco', + zip: '94102', + os: 'windows' + } +}); + +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', + 'city': 'sanfrancisco', + 'zip': '94102', + 'os': 'windows' + } +) + +browser = client.browsers.create( + proxy_id=proxy.id +) +``` + + + +## Configuration Parameters + +- **`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