Set up a self-hosted device fleet.

Run Bonk's device fabric on infrastructure you control. A node shares connected Android devices with other members of the fabric and can advertise itself as an SSH host. Bonk routes both adb and SSH connections through the fabric's WireGuard network.

For rented hardware, use Bonk Cloud. Self-hosting starts with your own machines, devices, and network setup.

What you need

A self-hosted Headscale control server and an appropriate access policy.
A pre-auth key for each member; node keys use the tag:bonk-node tag.
Bonk on the development machine and the machine serving devices.
Android devices attached to a node with adb access, or an SSH host.

Bonk runs its own tailscaled in userspace networking mode. It does not need a network adapter or admin rights for that process, and it does not change an existing Tailscale installation. Provisioning your server, firewall, or device can require separate privileges.

Join the fabric

Get the server address and pre-auth key from your fabric administrator. Replace the example values before running:

bonk fabric join --login-server https://headscale.example.com --auth-key YOUR_KEY
bonk fabric status

The join command starts the background connection. After rebooting, use bonk fabric up. Use bonk fabric down to stop it.

Share devices from a node

Join the node using a key tagged for nodes, then serve its devices:

bonk fabric join --login-server https://headscale.example.com --auth-key NODE_KEY --hostname lab
bonk node serve

To advertise the node as an SSH device, specify the port its SSH server listens on:

bonk node serve --ssh-port 2222

Use port 22 for a standard SSH server, or 2222 for the user SSH server configured by Bonk pairing. The node also exposes a filtered adb proxy on port 5038 and a device listing on port 5039 through the fabric. The adb server itself is not exposed directly.

The fabric access policy lets users reach nodes on ports 22, 2222, 5038, and 5039. Configure your policy before exposing a node, including restrictions on node-to-node and node-to-user access.

Use your remote hardware

bonk devices
bonk run --device lab/adb:SERIAL
bonk adb-bridge lab/adb:SERIAL
bonk shell ssh:dev@lab:2222

Bonk recognizes an SSH host by its fabric node name or fabric DNS name, such as lab.fabric.internal, and connects through the fabric. Configure SSH keys and known_hosts before connecting. bonk pair does not work through the fabric because nodes cannot call back to your development machine.

Local devices keep working without the fabric. Remote Android devices support forwarded ports, but do not currently support adb reverse.

Keep a node running

The upstream guide includes a systemd user service for Linux, a launch daemon for macOS, and Task Scheduler instructions for Windows. Use --skip-update in unattended services so the updater does not wait for input. On SteamOS, use the systemd service so the node survives logout. The macOS launch daemon's local-network exemption remains untested upstream.

Read the complete device fabric guide for service files, networking, and operational details.