# Proxy per Emulator Instance: Give Each Device Its Own IP > Attach one HTTP, HTTPS or SOCKS5 proxy per emulator instance or cloud device in Macro Automation Studio, test the exit IP and read it back in webhooks. Source: https://automationmacro.com/docs/proxies (Devices, updated 2026-09-04) A proxy per emulator instance or cloud device gives each one its own network identity. Macro Automation Studio (MAS) stores your proxies in your account, attaches one proxy to each device, and routes that device's traffic through it: with a local relay on an emulator, and with a transparent proxy inside the device's network on a cloud device. This page covers the proxy types, the two ways to add them, attaching, testing and limits. ## Before you start - A proxy to use: either an account with the residential gateway MAS integrates with, or endpoints from any other provider. - Devices in a [device group](/docs/device-groups). A proxy attaches to a device, not to a group. - MAS is installed and you are signed in with an active plan. ## Proxy types MAS accepts `http`, `https` and `socks5` proxies, with or without a username and password. Leave the credentials blank for an IP-authorized proxy. There are two ways to add proxies on the **Proxies** page: - **Gateway account** (the first tab): enter the login and password of your gateway account once. This adds one entry, and every device you attach it to gets its own sticky IP from the gateway. You can pick **Countries** (optional), choose **HTTP** or **SOCKS5** as the **Protocol**, and open **Advanced targeting** for state, city, ZIP or ASN. Narrower targeting requires a country and is billed by the provider at a higher rate, which the form says before you use it. - **Another provider**: enter a **Label**, **Protocol**, **Host / IP**, **Port** and optional **Username** and **Password**, or paste many proxies at once under **Paste proxies (one per line)** in any of these forms and click **Import & test**: ```text host:port host:port:user:pass scheme://user:pass@host:port ``` Click **Add & test**. MAS stores the credentials encrypted, then tests the proxy straight away. ## Test a proxy The **Proxy pool** table lists every proxy with its status: **live**, **dead** or **unchecked**. **Test** dials through the proxy to an IP echo service and records the exit IP, the exit country and the latency; **Test all** does it for the whole pool. The **Exit / geo** column shows what you asked for (**want:**) next to what the test observed (**got:**), because a gateway can exit somewhere other than the requested country. A gateway proxy is tested without a session, so its test exit is a rotating one. The **Data** column is the traffic MAS routed through the proxy over the last 30 days, measured by MAS's own relay. Your provider's billed figure can differ. ## Attach one proxy per emulator instance or cloud device One proxy per device. Attaching a second one replaces the first, and the dialog warns you: "This device already has a proxy. Attaching will replace it." From the **Proxies** page: 1. Click **Attach** on a proxy. 2. Choose the **Emulator device**. Devices that already have a proxy are marked "has a proxy". 3. Choose the **Session behavior**: **Sticky**, which pins one IP to this device, or **Rotating**, a fresh IP per request. 4. Click **Attach**. From a device card in **Device Groups**, open **Advanced settings** and pick the proxy in the **Proxy** dropdown. The card attaches it as sticky. **No proxy** removes the assignment. Every sticky assignment gets its own session id, which is what turns one gateway account into a distinct exit IP per device. For a plain proxy from another provider, the exit IP is whatever that endpoint gives; the session setting does not change it. The **Active assignments** table lists each device with its proxy and session. **Apply info** shows the resolved connection details, including the per-device username, for use outside MAS. ## How a SOCKS5 or HTTP proxy works on an Android emulator Android's global proxy setting has no field for a username and password, and a gateway's username is where the targeting and session id live. So MAS runs a small relay on this computer for each run: 1. When a run starts, MAS looks up the device's proxy and starts a relay bound to `127.0.0.1` on a free port. The relay adds the credentials on the way out and speaks HTTP to the device and HTTP, HTTPS or SOCKS5 to the upstream, so a SOCKS5 gateway works on an emulator that cannot speak SOCKS5 itself. 2. MAS sends one request through the relay to prove the path works and reads back the exit IP, country and city. Bad credentials or an unavailable region fail here, before the macro starts. 3. After adb connects, MAS runs `adb reverse` so the emulator's own localhost reaches the relay, then sets the device's global HTTP proxy to `127.0.0.1:`. This repeats on every reconnect, because a reconnect drops reverse mappings. 4. When the run ends, MAS clears the proxy setting, removes the reverse mapping and closes the relay. The device card narrates each step: **Proxy ready** after the check, **Proxy active** with the exit IP once applied, **Proxy off** after the run, and **Proxy failed** with the reason. The relay listens on loopback only, so nothing else on your network can use it. > [!WARNING] > Android's global proxy setting is advisory. An app that ignores it, which some games do, sends its traffic directly on an emulator. [Cloud devices](/cloud-devices) do not have this gap. ## How it works on a cloud device On a cloud device MAS does not use the Android setting at all. When the device starts, the host launches a transparent proxy inside the device's network namespace and redirects every outbound TCP connection through it. Each connection is reopened through your upstream proxy with your credentials, so all of the device's traffic exits from the proxy's IP whether or not the app honors a proxy. The cloud proxy talks to the upstream with HTTP CONNECT, so give a cloud device an HTTP or HTTPS proxy. - The proxy is applied for the life of the device, not per run. Attach or change it, then stop and start the device; the card says "Applies when the device next starts". - The card shows **Proxy** with the exit IP while the device is running, and each run's log starts with "Proxy active, traffic routed through ". - If the proxy cannot be applied, the device does not start un-proxied. It goes to **Error** with "proxy setup failed, turn the device off and on to retry". - A proxy attached while the device is already running is applied on a later poll without a restart. ## Exit IP in webhooks and run history When a proxy was active for a run, the run's webhook events carry `proxy_exit_ip` and `proxy_country` in `data`, next to `device_name`, `device_port` and `group_id`. The same values are stored with the run, so you can check later where a run's traffic exited. See [Webhooks](/docs/webhooks). ## Limits - One proxy per device; a device with no proxy connects directly. - Schemes: `http`, `https`, `socks5`. Port 1 to 65535. - Emulators apply the proxy per run; cloud devices apply it per device start and need an HTTP or HTTPS upstream. - Gateway targeting: either target countries or exclude countries, not both; state, city, ZIP and ASN need a country. - The usage figure is measured by MAS and is not your provider's bill. ## Proxy routes for API keys Every proxy route accepts an [API key](/docs/api-keys): `GET`, `POST` and `PUT` on `/api/proxy` and `/api/proxy/{id}`, `POST /api/proxy/import`, `POST /api/proxy/{id}/validate`, the assignment routes under `/api/proxy/assignments` with `/api/proxy/assignments/{id}/connection-info`, `GET /api/proxy/devices/{device_id}` for the proxy attached to a device, and `GET /api/proxy/usage`. Use `GET /api/emulator/devices` to find device ids. See the [REST API](/docs/rest-api). ## Troubleshooting ### Proxy failed on the device card The message names the step. "proxy did not respond, check credentials or targeting" means the upstream refused the check: wrong login, an expired plan, or a country the gateway has no IPs for. Run **Test** on the Proxies page to see the provider's answer. "could not expose the proxy relay to the device (adb reverse)" or "could not set the device proxy" means adb lost the emulator between connect and setup; see [ADB troubleshooting](/docs/adb-troubleshooting) and start the run again. ### Status shows dead The test could not reach the internet through the proxy. Check the host, port and scheme, then the credentials, and confirm the proxy allows this computer's IP if it is IP-authorized. **Test** again after fixing it; the latency and exit IP update on success. ### Cloud device shows proxy setup failed The device host could not apply the proxy at start. Check that the proxy is **live**, that it is an HTTP or HTTPS proxy rather than SOCKS5, then click **Stop**, wait, and **Start**. To start the device without a proxy, set its **Proxy** to **No proxy** first.