Document mobile proxies

docs.json

@@ -139,6 +139,7 @@
                           "proxies/overview",
                           "proxies/custom",
                           "proxies/residential",
+                          "proxies/mobile",
                           "proxies/isp",
                           "proxies/datacenter"
                         ]

proxies/mobile.mdx

@@ -0,0 +1,162 @@
+---
+title: "Mobile Proxies"
+---
+
+Mobile proxies route traffic through mobile carrier networks. Only recommended in advanced stealth use cases.
+
+<Info>
+Mobile carrier IPs often route through shared regional gateways. Country targeting is the most reliable option; city and US state targeting are best-effort and may not match every third-party geolocation database.
+</Info>
+
+## Configuration
+
+Create a mobile proxy with a target country:
+
+<CodeGroup>
+```typescript Typescript/Javascript
+import Kernel from '@onkernel/sdk';
+
+const kernel = new Kernel();
+
+const proxy = await kernel.proxies.create({
+  type: 'mobile',
+  name: 'my-us-mobile',
+  config: {
+    country: 'US'
+  }
+});
+
+const browser = await kernel.browsers.create({
+  proxy_id: proxy.id,
+});
+```
+
+```python Python
+from kernel import Kernel
+
+kernel = Kernel()
+
+proxy = kernel.proxies.create(
+    type='mobile',
+    name='my-us-mobile',
+    config={
+        'country': 'US'
+    }
+)
+
+browser = kernel.browsers.create(proxy_id=proxy.id)
+```
+</CodeGroup>
+
+## Configuration parameters
+
+- **`country`** - ISO 3166 country code. Must be provided when providing other targeting options.
+- **`state`** - US-only two-letter state code. Best-effort for mobile proxies.
+- **`city`** - Provider city alias, such as `brooklyn` or `chicago`. Best-effort for mobile proxies.
+- **`bypass_hosts`** (optional) - Array of hostnames that bypass the proxy and connect directly (max 100 entries)
+
+## Advanced targeting examples
+
+### Target by city
+
+Route traffic through a specific city:
+
+<CodeGroup>
+
+```typescript Typescript/Javascript
+const proxy = await kernel.proxies.create({
+  type: 'mobile',
+  name: 'brooklyn-mobile',
+  config: {
+    country: 'US',
+    state: 'NY',
+    city: 'brooklyn'
+  }
+});
+```
+
+```Python Python
+proxy = kernel.proxies.create(
+    type='mobile',
+    name='brooklyn-mobile',
+    config={
+        'country': 'US',
+        'state': 'NY',
+        'city': 'brooklyn'
+    }
+)
+```
+
+</CodeGroup>
+
+<Note>
+If the city alias is not matched, the API returns examples from the target state to help you find the correct value.
+</Note>
+
+### Target by state
+
+Route traffic through a US state:
+
+<CodeGroup>
+
+```typescript Typescript/Javascript
+const proxy = await kernel.proxies.create({
+  type: 'mobile',
+  name: 'ny-mobile',
+  config: {
+    country: 'US',
+    state: 'NY'
+  }
+});
+```
+
+```Python Python
+proxy = kernel.proxies.create(
+    type='mobile',
+    name='ny-mobile',
+    config={
+        'country': 'US',
+        'state': 'NY'
+    }
+)
+```
+
+</CodeGroup>
+
+## Bypass hosts
+
+Configure specific hostnames to bypass the proxy:
+
+<CodeGroup>
+```typescript Typescript/Javascript
+const proxy = await kernel.proxies.create({
+  type: 'mobile',
+  name: 'mobile-with-bypass',
+  config: {
+    country: 'US',
+  },
+  bypass_hosts: [
+    'localhost',
+    'metadata.google.internal',
+    '*.internal.company.com',
+  ],
+});
+```
+
+```python Python
+proxy = kernel.proxies.create(
+    type='mobile',
+    name='mobile-with-bypass',
+    config={
+        'country': 'US',
+    },
+    bypass_hosts=[
+        'localhost',
+        'metadata.google.internal',
+        '*.internal.company.com',
+    ]
+)
+```
+</CodeGroup>
+
+See the [overview](/proxies/overview#bypass-hosts) for full bypass host rules and examples.

proxies/overview.mdx

@@ -6,21 +6,22 @@ Kernel proxies enable you to route browser traffic through different types of pr
 
 ## Proxy Types
 
-Kernel supports four types of proxies:
+Kernel supports five types of proxies:
 
 1. [**Datacenter**](/proxies/datacenter) - Traffic routed through commercial data centers
 2. [**ISP**](/proxies/isp) - Traffic routed through data centers, using residential IP addresses leased from from internet service providers
 3. [**Residential**](/proxies/residential) - Traffic routed through real residential IP addresses
-4. [**Custom**](/proxies/custom) - Your own proxy servers
+4. [**Mobile**](/proxies/mobile) - Traffic routed through mobile carrier networks
+5. [**Custom**](/proxies/custom) - Your own proxy servers
 
-Datacenter has the fastest speed, while residential is least detectable. ISP is a balance between the two options, with less-flexible geotargeting. Kernel recommends to use the first option in the list that works for your use case.
+Datacenter has the fastest speed, while residential and mobile are least detectable. ISP is a balance between the options, with less-flexible geotargeting. Kernel recommends using the first option in the list that works for your use case.
 
 <Info>
 ISP proxies provide a **static exit IP that persists across sessions** — every browser session attached to the proxy exits through the same IP, and it only changes in rare ISP-initiated replacement events. This makes them suitable for IP allowlists or [managed auth](/auth/overview) health checks that must egress from a single IP.
 
 Datacenter proxies use **rotating exit IPs** — a new exit IP is assigned per request, so different requests within the same browser session can exit through different IPs. For a stable IP across requests and sessions, use an ISP proxy or a [custom (BYO) proxy](/proxies/custom) pointed at infrastructure you control.
 
-Residential proxies use **rotating exit IPs** that may change per connection — see [Residential Proxies](/proxies/residential#ip-rotation-behavior) for details.
+Residential and mobile proxies use **rotating exit IPs** that may change per connection — see [Residential Proxies](/proxies/residential#ip-rotation-behavior) and [Mobile Proxies](/proxies/mobile) for details.
 </Info>
 
 ## Create a proxy

reference/cli/proxies.mdx

@@ -27,12 +27,11 @@ Create a new proxy configuration. Proxy quality for bot detection avoidance, bes
 | `--name <name>` | Proxy configuration name. |
 | `--protocol <protocol>` | Protocol to use (`http` or `https`; default: `https`). |
 | `--country <code>` | ISO 3166 country code or `EU`. |
-| `--city <name>` | City name without spaces (e.g. `sanfrancisco`). Requires `--country`. |
-| `--state <code>` | Two-letter state code. |
-| `--zip <zip>` | US ZIP code. |
-| `--asn <asn>` | Autonomous system number (e.g. `AS15169`). |
-| `--os <os>` | Operating system (`windows`, `macos`, `android`). |
-| `--carrier <carrier>` | Mobile carrier. |
+| `--city <name>` | City name or provider alias. Residential and mobile; requires `--country`. |
+| `--state <code>` | State/region code. Residential, or US-only for mobile. |
+| `--zip <zip>` | ZIP/postal code. Residential only. |
+| `--asn <asn>` | Autonomous system number (e.g. `AS15169`). Residential only. |
+| `--os <os>` | Operating system (`windows`, `macos`, `android`). Residential only. |
 | `--host <host>` | Proxy host address or IP (`custom` type). |
 | `--port <port>` | Proxy port (`custom` type). |
 | `--username <username>` | Username for proxy authentication (`custom` type). |