Reaching a host server from the device¶
Use portReverse instead of running adb reverse yourself. It lets an app or
browser on an Android device reach a server on your machine at exactly
http://localhost:<port>, such as an OAuth redirect URI or a local mock backend.
Port reverse internals describes
how AutoMobile tracks mappings.
On iOS the tool returns status: "not_applicable": a simulator shares the
host’s network, so localhost:<port> already reaches your machine.
Actions¶
ensure¶
ensure with ports: [{ devicePort, hostPort? }] adds each mapping. hostPort
defaults to devicePort. Calling it again is a no-op.
With reclaimStale: true, ensure replaces a stale mapping instead of reporting
a conflict. A crashed session, a daemon restart, or another tool can leave such a
mapping behind. AutoMobile replaces it only when all of these hold:
- your session holds the device;
- no running session owns the mapping;
- its host side is
tcp:<H>; - nothing on your machine accepts a connection on port
H.
That mapping’s result carries reclaimed: { host, reason: "host_refused" }. When
adb talks to a server on another machine (ANDROID_ADB_SERVER_ADDRESS or
ADB_SERVER_SOCKET), AutoMobile cannot check host ports, so it reclaims nothing.
list¶
list returns every reverse on the device:
| Field | Meaning |
|---|---|
owned: true |
Your session created the mapping. |
owner |
"prototype" when a shown or saved prototype’s via: "device" request uses it. |
hostListening |
Whether a server on your machine accepts connections on the mapping’s tcp: host port; absent when unchecked. |
deviceListener¶
list and verify give each port a deviceListener:
| Value | Meaning |
|---|---|
{ kind: "none" } |
Nothing listens on the device port. |
{ kind: "reverse" } |
The reverse itself listens. |
{ kind: "process", uid, package? } |
An app or other process on the device holds the port; package is set when exactly one package has that uid. |
{ kind: "unsupported", detail } |
The device would not show its listening sockets. |
verify¶
verify reports whether each port has a mapping now. It checks all of your ports
by default. Ports without a mapping report missing, and AutoMobile does not probe
them.
With probe: true it also connects to each mapped port from the device. This
takes about a second, for all ports at once. Each port then reports one of:
reachable: your host server accepted and kept the connection open.unreachable, with aprobeReason:closed(the mapping exists but nothing listens on the host port),refused(nothing listens on the device port), ortimeout(the device did not answer).probe_unsupported: the device shell has no usable connect command;probeDetailholds what it printed.
A host server that closes idle connections within a second reads as closed.
HTTP probe¶
A TCP connect succeeds for any server, including the wrong one on a reused host
port. To check that the right service answers, pass
probe: { http: { path, expectStatus, hostHeader?, expectBodyContains?, timeoutMs? } }.
The device sends GET <path> through each mapping and reports httpStatus.
A port is reachable when the status is in expectStatus and the body contains
expectBodyContains, when given. Otherwise it is unreachable with one of these
probeReason values:
probeReason |
Meaning |
|---|---|
http_status |
Another status came back. |
http_body |
The expected text is missing. |
no_http_response |
The connection ended, or something answered, without an HTTP response; probeDetail shows what came back. |
refused |
Nothing listens on the device port. |
timeout |
No answer in time. Responses over 256 KB are not read and also report timeout. |
| Parameter | Rule |
|---|---|
path |
Must start with / and contain no spaces. |
hostHeader |
Defaults to localhost:<devicePort>. |
timeoutMs |
1000-10000, default 2000, rounded up to whole seconds. |
remove¶
remove deletes mappings your session created. A port a prototype also uses
reports released: your session no longer owns it, and it stays on the device
until the prototype is dismissed. Likewise, ensure on a prototype’s port to the
same host port shares it (present) instead of conflicting.
Lost mappings¶
AutoMobile owns the mappings it creates for your session. A mapping can disappear
after an adb server restart, adb reconnect, adb root/unroot, an emulator
restart, or adb reverse --remove run outside AutoMobile.
AutoMobile re-adds a lost mapping when it sees the device’s adb connection
recover, or on its periodic check (every 30 s by default). Otherwise the next
ensure, list or verify call re-adds it. Either way, that next call lists it
in restored. A mapping AutoMobile could not re-add appears in
restoreFailures, and the next call retries it.
AutoMobile removes your mappings when your session is released or leaves the
device. Mappings made without a session stay until the device disconnects, and
AutoMobile stops tracking them then. A device that stays connected keeps them
until you run adb reverse --remove.
Errors¶
Errors come back with errorCode:
errorCode |
Meaning and what to do |
|---|---|
port_reverse_conflict |
Someone else already maps the device port, or it maps to another host port. Nothing changed; pick another port or remove the existing mapping. conflicts lists each port’s conflictKind (see below). |
port_reverse_device_port_in_use |
A process on the device already listens on the device port, so the reverse cannot be added. The message names its uid and package; stop it or pick another device port. |
port_reverse_reclaim_failed |
reclaimStale found a stale mapping but could not remove it, or it changed just before removal. That mapping stays as it was and this call’s new mappings roll back; a mapping the same call already reclaimed stays removed. Call list to see the current mappings. |
port_reverse_not_owned |
remove named a port your session did not create. Nothing was removed. |
port_reverse_port_refused |
A port is below 1024 or outside AUTOMOBILE_PORT_REVERSE_ALLOWED_PORTS, or ports was missing. |
conflictKind also appears at the top level when every port has the same one:
conflictKind |
Meaning |
|---|---|
other_session |
Another running session owns the mapping. |
prototype |
A prototype’s request uses it, mapped to another host port. |
external_live |
Made outside AutoMobile, and its host port accepts connections. |
external_unknown |
Made outside AutoMobile, and its host port was not shown to be live. Retry with reclaimStale: true to replace it if stale. |