> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxies

> Use managed Mobilerun Connect proxies or bring your own proxy for device traffic.

Mobilerun provides managed proxies through **Mobilerun Connect**. You can use a Connect proxy for your Android Phone, or bring your own SOCKS5 proxy. You do not need to purchase a proxy from another provider to use Mobilerun.

Personal Phones can use their own network connection. Proxy support depends on the device; check its capabilities before attaching one through the API.

## Mobilerun Connect

Choose a proxy type and country for your automation:

| Type | Use case | Billing |
| - | - | - |
| **Dedicated residential** | Keep a consistent residential IP for a long-lived device or account | Uses an included proxy allowance when available, otherwise a separate subscription |
| **Residential** | Residential traffic with sticky or rotating IPs | Based on traffic usage |
| **Mobile** | Traffic through a mobile carrier | Availability and terms depend on your account; contact us for access |

Check the [Connect product page](https://mobilerun.ai/connect) and your dashboard for current plans and availability. The country catalog at `GET /v1/connect/countries` lists the available proxy types by country.

### Create a managed proxy

Open the proxy section of the [dashboard](https://cloud.mobilerun.ai) and choose the country and available Connect proxy type. Complete checkout if required, and wait for the proxy to become active before attaching it to a phone.

For API integrations, create a dedicated residential proxy with:

```bash theme={null}
curl --fail-with-body https://api.mobilerun.ai/v1/connect/proxies \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"us","type":"dedicated_residential"}'
```

Creation can require payment. The response includes the proxy ID and may include a `paymentUrl` for checkout. Poll `GET /v1/connect/proxies/{id}` while the proxy is `checking`, `pending_payment`, or `provisioning`; it is ready when its status becomes `active`. If payment is pending, complete checkout before expecting provisioning to finish.

The creation response also includes proxy credentials. Keep them private. When attaching the proxy to a device, reference its ID so Mobilerun resolves the credentials for you.

### Attach a Connect proxy to a device

Select the active proxy during device setup, or attach an existing proxy through the device API:

```bash theme={null}
curl --fail-with-body -X POST "https://api.mobilerun.ai/v1/devices/<DEVICE_ID>/proxy" \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connect":{"id":"<PROXY_ID>"},"smartIp":true}'
```

The proxy must belong to the same owner as the device. To provision or reuse a rotating residential proxy for a device, use `"connect":{"country":"us"}` instead. A country reference can incur proxy usage charges; it does not select a dedicated residential proxy.

Pass exactly one of `connect.id` or `connect.country`. Do not combine a Connect reference with SOCKS5 credentials in the same request.

## Bring Your Own Proxy

If you already have a proxy provider, you can still register its SOCKS5 endpoint and select it for your device. Provide the host, port, username, and password in the dashboard's custom proxy form.

For the device API, use the `socks5` object instead of `connect`:

```json theme={null}
{
  "socks5": {
    "host": "proxy.example.com",
    "port": 1080,
    "user": "username",
    "password": "password"
  },
  "smartIp": true
}
```

The examples on this page cover the device API's SOCKS5 and Connect options. See [Mobilerun Connect](https://mobilerun.ai/connect) for other network offerings.

## Smart IP

Enable `smartIp` to align the device with the proxy's exit IP. It configures GPS location, timezone, locale, and, when no eSIM is active, mobile carrier and network type. It works with both Connect references and custom SOCKS5 proxies.

Use a proxy country that matches the device's intended location and locale. After connecting, query `GET /v1/devices/{deviceId}/proxy` to verify the proxy state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.