Proxy per Emulator Instance: Give Each Device Its Own IP

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. 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:

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:<relay port>. 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.

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.

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: 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.

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 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.