BuildRelayKit

BuildRelayKit is a terminal-first Android remote development bridge for Windows. It lets ADB and Fastboot commands on a remote Windows or WSL development machine operate on Android devices physically connected by USB to another Windows PC.

BuildRelayKit authenticates with OpenSSH, creates encrypted reverse forwards, installs Remote Windows wrappers and lightweight WSL shims, verifies both paths, and supervises the relay until you disconnect it.

Android device(s) <--USB--> Device-host Windows PC
                              |
                              | encrypted SSH relay
                              v
                    Remote Windows PowerShell
                              |
                              v
                         Remote WSL

Requirements

Device-host Windows PC:

• Node.js 20 or newer and npm.
• adb and fastboot available on PATH.
• USB debugging authorized on the connected device.
• Network access to the remote Windows SSH server.

Remote Windows PC:

• OpenSSH Server accepting the chosen Windows account.
• PowerShell and at least one WSL distribution.
• Windows-to-WSL interoperability enabled.
• Internet access if Android Platform Tools must be downloaded.

Install

Install globally when the command should be available in every terminal:

npm.cmd install --global buildrelaykit
buildrelaykit.cmd --help

For a project-local installation:

npm.cmd install buildrelaykit
npx.cmd buildrelaykit --help

Use the .cmd forms when PowerShell's execution policy blocks npm.ps1 or another generated PowerShell launcher.

Quick start

Run BuildRelayKit on the Windows PC holding the USB cable.

adb devices -l
buildrelaykit.cmd relay localhost --device <serial> --wsl <distribution> '<user>@<remote-host>'

Example:

buildrelaykit.cmd relay localhost --device 3A120DLJH000ZL --wsl Ubuntu-22.04 '[email protected]'

Enter the remote Windows account password at the OpenSSH prompt when requested. Passwords are not accepted as command arguments and are not stored by BuildRelayKit.

Wait for:

[remote 5/5] Verification complete.
[remote] Relay is ready.
READY

Keep the relay terminal open while using ADB or Fastboot remotely.

Device selection

Exactly one device policy is required.

Target one serial:

buildrelaykit.cmd relay localhost --device <serial> --wsl <distribution> '<user>@<remote-host>'

Target every connected device:

buildrelaykit.cmd relay localhost --all-devices --wsl <distribution> '<user>@<remote-host>'

Omitting both --device and --all-devices fails; BuildRelayKit never silently selects all devices. The two options cannot be combined.

With --device, generated ADB and Fastboot wrappers automatically select that serial for device-specific commands. With --all-devices, choose a device per operation when necessary:

adb -s <serial> shell
fastboot -s <serial> getvar product

Device selection controls the generated wrappers, not trust boundaries. Only relay to remote Windows accounts and computers you trust.

WSL selection

Use --wsl for predictable selection when the remote PC has more than one distribution:

--wsl Ubuntu-22.04

If --wsl is omitted, BuildRelayKit selects the first distribution returned by wsl.exe --list --quiet on the remote Windows PC:

buildrelaykit.cmd relay localhost --device <serial> '<user>@<remote-host>'

If no distribution is installed, bootstrap fails rather than reporting READY. Only the selected distribution is configured.

What happens after login

BuildRelayKit prints progress while it:

1. inspects or installs Android Platform Tools remotely;
2. configures Remote Windows ADB and Fastboot wrappers;
3. discovers and selects WSL;
4. installs ADB and Fastboot shims in ~/.local/bin;
5. verifies both tools from Remote PowerShell and WSL.

No separate profile or bootstrap command is required for the normal relay workflow.

Use from Remote Windows and WSL

After READY, PowerShell sessions for the same remote Windows account can run:

adb devices
adb shell
adb push .\local-file.txt /data/local/tmp/
adb pull /data/local/tmp/remote-file.txt .
fastboot devices
fastboot getvar product

Inside the configured WSL distribution:

adb devices
adb shell
adb push ./image.zip /data/local/tmp/
fastboot devices
fastboot getvar product

This works from SSH or Parsec because the wrappers belong to the remote Windows account, not to the interactive transport used to open the terminal. Open a new remote terminal after the first bootstrap if an older terminal does not see the updated PATH.

Stop or inspect the relay

• Keep the originating terminal open while the relay is needed.
• Press Ctrl+C there to stop it cleanly.
• Run buildrelaykit.cmd status on the device-host PC to inspect session state.
• Run buildrelaykit.cmd disconnect from another device-host terminal to stop the recorded relay.

Troubleshooting

npm.ps1 cannot be loaded: use npm.cmd, npx.cmd, and buildrelaykit.cmd.

Permission denied: test ssh '<user>@<remote-host>' directly and verify the Windows account and SSH server. Supply the password only at OpenSSH's prompt.

Device ... was not found: run adb devices -l, authorize USB debugging, and copy the serial exactly. Use fastboot devices when the device is already in Fastboot mode.

Wrong WSL selected: list distributions on Remote Windows with wsl.exe --list --quiet, then pass the exact name with --wsl.

WSL Exec format error: rerun the relay so BuildRelayKit can repair WSLInterop. If /etc/wsl.conf explicitly sets [interop] enabled=false, enable it, run wsl.exe --shutdown, and relay again.

Another relay is active: stop the existing terminal with Ctrl+C or run buildrelaykit.cmd disconnect.

No READY: read the last printed stage. BuildRelayKit does not claim readiness unless SSH forwarding and both ADB/Fastboot paths verify successfully.

Safety

Fastboot flashing, updates, erases, and ADB sideload operations can damage or erase a device. Confirm the serial, device state, active slot, image hash, and hardware compatibility before issuing destructive commands.

BuildRelayKit is an early Phase 1 release. See the full GitHub README, relay documentation, and manual validation guide.