Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

feat(hostbridge): add podroid-phone-ip to print the phone's address

ExTv57877affe88d
diff --git a/CLAUDE.md b/CLAUDE.md
index a436894..9c9bbaf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -110,7 +110,7 @@ On **AVF** there is no QMP and no PL011: the console is captured via `ConsoleFan
### Guest → Android host bridge
-Lets guest processes call back to Android. Guest side: `podroid-hostd` (multi-call C binary, `build-rootfs/host-bridge/podroid-hostd.c`) owns a guest-local `AF_UNIX` socket `/run/podroid-host.sock`; `argv[0]` dispatch also exposes it as `podroid-notify` and `podroid-forward` (symlinks). The daemon relays one request line / one response line to Android over a backend transport: `/dev/hvc2` on QEMU, `AF_VSOCK:9101` on AVF (chosen by the `podroid.backend=avf` cmdline marker). Android side: `engine/hostbridge/` - `HostRequestServer` reads requests over a `HostTransport` (`QemuHostTransport` via `LocalSocket` to `host.sock`, or `AvfHostTransport` via `connectVsock`), `HostRequestDispatcher` parses them, and routes to `NotificationPoster` (posts via `NotificationManagerCompat`) or `PortForwardRepository` (rules persist and `EngineHolder` applies them live). `PodroidService` starts/stops the server over the VM lifecycle. Stop or parent cancellation shuts down the active transport to unblock reads; a transport returned by a late native connect is closed without dispatching. Android accepts only complete UTF-8 request lines up to 8191 bytes (matching the guest buffer). Free-text fields are base64 (`HostProtocol.kt`) so UTF-8 survives. The daemon also self-originates a `STATS containers=<n>` push (inotify-driven, debounced) whenever the podman container count changes, which `HostRequestDispatcher` persists to the `last_container_count` DataStore key for `HomeViewModel` to show live on Home - the same channel on both backends, no polling.
+Lets guest processes call back to Android. Guest side: `podroid-hostd` (multi-call C binary, `build-rootfs/host-bridge/podroid-hostd.c`) owns a guest-local `AF_UNIX` socket `/run/podroid-host.sock`; `argv[0]` dispatch also exposes it as `podroid-notify`, `podroid-forward`, and `podroid-phone-ip` (symlinks). The daemon relays one request line / one response line to Android over a backend transport: `/dev/hvc2` on QEMU, `AF_VSOCK:9101` on AVF (chosen by the `podroid.backend=avf` cmdline marker). Android side: `engine/hostbridge/` - `HostRequestServer` reads requests over a `HostTransport` (`QemuHostTransport` via `LocalSocket` to `host.sock`, or `AvfHostTransport` via `connectVsock`), `HostRequestDispatcher` parses them, and routes to `NotificationPoster` (posts via `NotificationManagerCompat`), `PortForwardRepository` (rules persist and `EngineHolder` applies them live), or the `PHONE-IP` verb (`podroid-phone-ip` CLI, backed by `NetworkUtils.allLocalIpv4`, returning a base64 `iface address` table, primary first). `PodroidService` starts/stops the server over the VM lifecycle. Stop or parent cancellation shuts down the active transport to unblock reads; a transport returned by a late native connect is closed without dispatching. Android accepts only complete UTF-8 request lines up to 8191 bytes (matching the guest buffer). Free-text fields are base64 (`HostProtocol.kt`) so UTF-8 survives. The daemon also self-originates a `STATS containers=<n>` push (inotify-driven, debounced) whenever the podman container count changes, which `HostRequestDispatcher` persists to the `last_container_count` DataStore key for `HomeViewModel` to show live on Home - the same channel on both backends, no polling.
> **Gotcha:** `/dev/hvc2` is a virtio-console **TTY** that defaults to echo on. The daemon must `cfmakeraw()` it, or the TTY echoes Android's responses back and the protocol desyncs after the first request. AVF (a raw vsock socket) is unaffected.
diff --git a/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt b/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt
index 6974722..7739cf3 100644
--- a/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt
+++ b/app/src/main/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcher.kt
@@ -11,6 +11,7 @@ package com.excp.podroid.engine.hostbridge
import com.excp.podroid.data.repository.AddRuleResult
import com.excp.podroid.data.repository.MAX_PORT_FORWARD_RULES
import com.excp.podroid.data.repository.PortForwardRule
+import com.excp.podroid.util.NetworkUtils
import kotlinx.coroutines.CancellationException
class HostRequestDispatcher(
@@ -23,6 +24,7 @@ class HostRequestDispatcher(
private val power: suspend (String) -> String,
private val setHeadless: suspend (String) -> String,
private val setContainerCount: suspend (Int) -> Unit,
+ private val phoneAddresses: suspend () -> List<NetworkUtils.LocalAddress>,
) {
private val validProtocols = setOf("tcp", "udp")
@@ -48,6 +50,7 @@ class HostRequestDispatcher(
"POWER" -> handlePower(parts)
"HEADLESS" -> handleHeadless(parts)
"STATS" -> handleStats(parts)
+ "PHONE-IP" -> handlePhoneIp(parts)
"PING" -> "PONG"
else -> HostProtocol.err("bad request")
}
@@ -152,4 +155,13 @@ class HostRequestDispatcher(
setContainerCount(count)
return HostProtocol.ok()
}
+
+ // PHONE-IP (no arguments)
+ private suspend fun handlePhoneIp(p: List<String>): String {
+ if (p.size != 1) return HostProtocol.err("bad request")
+ val addresses = phoneAddresses()
+ if (addresses.isEmpty()) return HostProtocol.err("no network")
+ val table = addresses.joinToString("\n") { "${it.iface} ${it.address}" }
+ return HostProtocol.ok(HostProtocol.enc(table))
+ }
}
diff --git a/app/src/main/java/com/excp/podroid/service/PodroidService.kt b/app/src/main/java/com/excp/podroid/service/PodroidService.kt
index e442236..7b55518 100644
--- a/app/src/main/java/com/excp/podroid/service/PodroidService.kt
+++ b/app/src/main/java/com/excp/podroid/service/PodroidService.kt
@@ -338,6 +338,7 @@ class PodroidService : Service() {
power = { handlePowerRequest(it) },
setHeadless = { handleHeadlessRequest(it) },
setContainerCount = { settingsRepository.setLastContainerCount(it) },
+ phoneAddresses = { withContext(Dispatchers.IO) { NetworkUtils.allLocalIpv4(this@PodroidService) } },
)
return com.excp.podroid.engine.hostbridge.HostRequestServer(
openTransport = { engine.openHostTransport() },
diff --git a/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt b/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt
index 515582c..0ae98ca 100644
--- a/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt
+++ b/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestDispatcherTest.kt
@@ -5,6 +5,7 @@ import org.junit.Assert.assertNull
import org.junit.Test
import com.excp.podroid.data.repository.AddRuleResult
import com.excp.podroid.data.repository.PortForwardRule
+import com.excp.podroid.util.NetworkUtils
import kotlinx.coroutines.runBlocking
import org.junit.Assert.assertTrue
@@ -37,6 +38,7 @@ private fun dispatcher(
power: suspend (String) -> String = { HostProtocol.ok() },
setHeadless: suspend (String) -> String = { HostProtocol.ok() },
setContainerCount: suspend (Int) -> Unit = {},
+ phoneAddresses: suspend () -> List<NetworkUtils.LocalAddress> = { emptyList() },
addResult: AddRuleResult = AddRuleResult.ADDED,
) = HostRequestDispatcher(
notifications = poster,
@@ -54,6 +56,7 @@ private fun dispatcher(
power = power,
setHeadless = setHeadless,
setContainerCount = setContainerCount,
+ phoneAddresses = phoneAddresses,
)
class HostRequestDispatcherTest {
@@ -242,4 +245,26 @@ class HostRequestDispatcherTest {
assertTrue(d.handle("STATS count=3").startsWith("ERR "))
assertEquals(null, seen)
}
+
+ @Test fun phoneIpReturnsPrimaryFirstFormattedTable() = runBlocking {
+ val addresses = listOf(
+ NetworkUtils.LocalAddress("wlan0", "192.168.1.5"),
+ NetworkUtils.LocalAddress("rndis0", "192.168.42.1"),
+ )
+ val resp = dispatcher(phoneAddresses = { addresses }).handle("PHONE-IP")
+ assertTrue(resp.startsWith("OK "))
+ val table = HostProtocol.dec(resp.removePrefix("OK "))
+ assertEquals("wlan0 192.168.1.5\nrndis0 192.168.42.1", table)
+ }
+
+ @Test fun phoneIpEmptyIsError() = runBlocking {
+ val resp = dispatcher(phoneAddresses = { emptyList() }).handle("PHONE-IP")
+ assertTrue(resp.startsWith("ERR "))
+ assertEquals("no network", HostProtocol.dec(resp.removePrefix("ERR ")))
+ }
+
+ @Test fun phoneIpRejectsExtraTokens() = runBlocking {
+ val d = dispatcher(phoneAddresses = { listOf(NetworkUtils.LocalAddress("wlan0", "192.168.1.5")) })
+ assertTrue(d.handle("PHONE-IP extra").startsWith("ERR "))
+ }
}
diff --git a/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestServerTest.kt b/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestServerTest.kt
index 5f63bdf..17b7208 100644
--- a/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestServerTest.kt
+++ b/app/src/test/java/com/excp/podroid/engine/hostbridge/HostRequestServerTest.kt
@@ -2,6 +2,7 @@ package com.excp.podroid.engine.hostbridge
import com.excp.podroid.data.repository.AddRuleResult
import com.excp.podroid.data.repository.PortForwardRule
+import com.excp.podroid.util.NetworkUtils
import java.io.IOException
import java.util.concurrent.CountDownLatch
import java.util.concurrent.TimeUnit
@@ -246,6 +247,7 @@ class HostRequestServerTest {
power = { HostProtocol.ok() },
setHeadless = { HostProtocol.ok() },
setContainerCount = {},
+ phoneAddresses = { emptyList<NetworkUtils.LocalAddress>() },
)
private class BlockingTransport(private val resultAfterClose: String? = null) : HostTransport {
diff --git a/build-rootfs/build-rootfs.sh b/build-rootfs/build-rootfs.sh
index 6105097..b95522a 100755
--- a/build-rootfs/build-rootfs.sh
+++ b/build-rootfs/build-rootfs.sh
@@ -130,6 +130,7 @@ ln -sf podroid-hostd "$ROOTFS/usr/local/bin/podroid-open"
ln -sf podroid-hostd "$ROOTFS/usr/local/bin/podroid-power"
ln -sf podroid-hostd "$ROOTFS/usr/local/bin/podroid-headless"
ln -sf podroid-hostd "$ROOTFS/usr/local/bin/podroid-server"
+ln -sf podroid-hostd "$ROOTFS/usr/local/bin/podroid-phone-ip"
chmod +x "$ROOTFS/usr/local/bin/podroid-"*
# vsock agent's initial forward table (read at podroid-vsock startup).
mkdir -p "$ROOTFS/etc/podroid"
diff --git a/build-rootfs/host-bridge/podroid-hostd.c b/build-rootfs/host-bridge/podroid-hostd.c
index 9fa3844..45415fb 100644
--- a/build-rootfs/host-bridge/podroid-hostd.c
+++ b/build-rootfs/host-bridge/podroid-hostd.c
@@ -11,6 +11,7 @@
* podroid-open CLI: open a URL on Android (ACTION_VIEW).
* podroid-power CLI: stop/restart the VM, or query status.
* podroid-headless CLI (alias podroid-server): toggle server mode.
+ * podroid-phone-ip CLI: print the phone's reachable IPv4 address(es).
*
* Daemon transport (one request line -> one response line, serialized):
* AVF (podroid.backend=avf in /proc/cmdline): listen AF_VSOCK :9101, accept
@@ -345,6 +346,54 @@ static int cli_headless(int argc, char **argv) {
return cli_report(resp, 0);
}
+/* Default output is the primary address alone (one bare line) so
+ * `$(podroid-phone-ip)` works in scripts; -a/--all prints every "iface
+ * address" line the host reports, primary first. */
+static int cli_phone_ip(int argc, char **argv) {
+ int all = 0;
+ if (argc >= 2) {
+ if (strcmp(argv[1], "-a") == 0 || strcmp(argv[1], "--all") == 0) {
+ all = 1;
+ } else if (strcmp(argv[1], "-h") == 0 || strcmp(argv[1], "--help") == 0) {
+ printf("usage: podroid-phone-ip [-a|--all]\n");
+ return 0;
+ } else {
+ fprintf(stderr, "usage: podroid-phone-ip [-a|--all]\n");
+ return 2;
+ }
+ }
+ char resp[8192];
+ int rc = cli_roundtrip("PHONE-IP", resp, sizeof(resp));
+ if (rc < 0) return cli_roundtrip_failed(rc);
+ if (strncmp(resp, "ERR ", 4) == 0) {
+ char *msg = b64decode(resp + 4);
+ fprintf(stderr, "podroid: %s\n", msg ? msg : "error");
+ free(msg);
+ return 1;
+ }
+ if (strncmp(resp, "OK ", 3) != 0) {
+ fprintf(stderr, "podroid: unexpected response: %s\n", resp);
+ return 1;
+ }
+ char *table = b64decode(resp + 3);
+ if (!table || !*table) {
+ fprintf(stderr, "podroid: no network\n");
+ free(table);
+ return 1;
+ }
+ if (all) {
+ printf("%s\n", table);
+ } else {
+ /* First line is "iface address"; print the address field only. */
+ char *nl = strchr(table, '\n');
+ if (nl) *nl = '\0';
+ char *sp = strchr(table, ' ');
+ printf("%s\n", sp ? sp + 1 : table);
+ }
+ free(table);
+ return 0;
+}
+
/* On QEMU the host channel is /dev/hvc2, a virtio-console TTY that defaults to
* cooked mode with ECHO on. Echo is fatal here: every response the guest reads
* gets echoed straight back out to Android, which then parses its own "OK ..."
@@ -668,5 +717,6 @@ int main(int argc, char **argv) {
if (strcmp(base, "podroid-open") == 0) return cli_open(argc, argv);
if (strcmp(base, "podroid-power") == 0) return cli_power(argc, argv);
if (strcmp(base, "podroid-headless") == 0 || strcmp(base, "podroid-server") == 0) return cli_headless(argc, argv);
+ if (strcmp(base, "podroid-phone-ip") == 0) return cli_phone_ip(argc, argv);
return daemon_main();
}
diff --git a/docs/guide/networking.html b/docs/guide/networking.html
index b140826..029ebb0 100644
--- a/docs/guide/networking.html
+++ b/docs/guide/networking.html
@@ -176,9 +176,21 @@ podroid-server off
podroid-server status</code></pre>
<p>Server mode keeps the VM running behind a pure-black, minimum-brightness full-screen overlay - for leaving the phone on a headless workload with minimal OLED draw and burn-in. The screen stays on (so the system does not kill the VM) but shows nothing. Exit by <strong>holding the screen for three seconds</strong>, or run <code>podroid-server off</code>. The same toggle lives in the terminal's top bar. <code>podroid-headless</code> is an alias for <code>podroid-server</code>.</p>
+ <h3><code>podroid-phone-ip</code> - print the phone's IP from inside the guest</h3>
+ <pre><code><span class="c"># the primary address only, one bare line - safe to use in scripts</span>
+podroid-phone-ip
+<span class="c"># every reachable address, one "iface address" line each, primary first</span>
+podroid-phone-ip -a</code></pre>
+ <p>Saves a trip to the Status screen when a script or shell session needs the phone's own LAN address, for example to fill in <code>pasv_address</code> for the FTP server below or to print a URL a teammate can open. <code>$(podroid-phone-ip)</code> expands to just the address. Fails with a non-zero exit code and a message on stderr if the host bridge is unreachable or the phone has no usable address.</p>
+
+ <div class="callout note">
+ <span class="label">Using it from a container</span>
+ <p>Bind-mount the host bridge socket and the binary into the container: <code>-v /run/podroid-host.sock:/run/podroid-host.sock -v /usr/local/bin/podroid-hostd:/usr/local/bin/podroid-phone-ip:ro</code>. The binary is built statically, so it has no libc dependency at runtime and works from any container image, Alpine-based or not.</p>
+ </div>
+
<div class="callout note">
<span class="label">How it works</span>
- <p>A small guest daemon (<code>podroid-hostd</code>) relays each request to the Android side over the same control transport the app already uses - a virtio-console port on QEMU, vsock on AVF - which then performs the requested action: post a notification, write a port-forward rule, open a URL, or control the VM. Any process that can reach the guest socket can use these, so they work from a container too if you bind-mount <code>/run/podroid-host.sock</code> into it.</p>
+ <p>A small guest daemon (<code>podroid-hostd</code>) relays each request to the Android side over the same control transport the app already uses - a virtio-console port on QEMU, vsock on AVF - which then performs the requested action: post a notification, write a port-forward rule, open a URL, control the VM, or read back the phone's own address. Any process that can reach the guest socket can use these, so they work from a container too if you bind-mount <code>/run/podroid-host.sock</code> into it.</p>
</div>
<h2>LAN reachability</h2>