Reach services on your own devices, wherever you are.
Forwiroh connects an Android phone, iPhone, Linux machine or Mac to trusted peers through encrypted Iroh connections. Run it on your home computer, scan its pairing QR with your phone, approve the request, and open a local port that reaches a service at home. You can pair several devices and run several tunnels at once.
You do not need an email account, public IP address or router port forwarding. Iroh tries a direct connection and can use an encrypted relay when necessary. TCP forwarding and SOCKS5 work without root or a VPN interface.
This is an early implementation, under active validation. Platform builds and automated tests do not replace physical-device testing. See the implementation checklist, Android guide and iOS guide for verification details and limitations.
| Feature | What it does | Example |
|---|---|---|
| TCP forward | A port on this device connects to a destination on a peer. | Reach home SSH at 127.0.0.1:2222, or a home web app at 127.0.0.1:8080. |
| Reverse forward | A port on the peer connects back to a destination on this device. | Let the home machine reach your laptop's development server. |
| SOCKS5 proxy | SOCKS-aware applications send TCP connections through a chosen peer; the peer resolves destination names. | Use curl through your home network without changing system routes. |
| VPN | Selected routes, or full IPv4/IPv6 internet traffic on iOS, use a paired rootless exit peer. | Reach a private network or route phone traffic through a home peer. |
| Peer management | Pair, rename, disconnect, restrict or revoke trusted devices. | Keep separate home, laptop and phone peers. |
Pairing establishes trust; it does not automatically create tunnels or redirect traffic. After pairing, choose one of the connection types above.
| Platform | Interface | Background networking |
|---|---|---|
| Android 8.0+ | Native app in apps/android: QR scanner, peers, tunnels and VPN |
A foreground service runs while its notification is active. |
| iPhone / iPad, iOS 17+ | Native SwiftUI app in apps/ios: QR scanner, peers, tunnels, TCP diagnostics and VPN |
Ordinary socket tunnels require the app in the foreground; VPN runs in a Packet Tunnel extension. |
| Linux | forwiroh CLI and daemon |
Keep serve running, optionally as a user systemd service. Supports a pre-provisioned VPN TUN. |
| macOS | forwiroh CLI and daemon; native SwiftUI app in apps/macos |
Keep serve running. CLI VPN is not implemented. |
| Windows 10/11 | Native forwiroh.exe CLI and daemon |
Keep serve running. Uses an owner-only local named pipe; CLI VPN is not implemented. |
The mobile apps and CLI share the same Rust networking and authorization core. Android stores the identity encrypted with a Keystore key; iOS uses Keychain. Saved peers persist. iOS restores saved forward, SOCKS and reverse profiles in its VPN extension; other active tunnel configurations must be recreated after a networking restart.
The flake provides the forwiroh package, a development shell, and a NixOS
module. On NixOS, the module installs the CLI and starts the Forwiroh daemon as
a system service.
inputs.forwiroh.url = "github:AbhiTheModder/forwiroh";
modules = [
inputs.forwiroh.nixosModules.default
];
programs.forwiroh.enable = true;When using a local checkout, use a path input instead:
inputs.forwiroh.url = "path:/home/<user>/forwiroh";After rebuilding, pair devices and create forwards with the forwiroh CLI. The
module does not configure OpenSSH, peer permissions, tunnels, or lid and power
behavior.
To try the CLI without installing it:
nix run github:trufae/forwiroh -- --helpTo build the package from a local checkout:
nix build .#forwirohFor development, choose either the flake shell or the legacy shell. To run the
CLI from the checkout, use nix run:
nix run . -- --help
nix develop
# Or: nix-shell nix/shell.nix
cargo buildLinux, macOS, and Android (Termux):
curl -fsSL https://github.com/trufae/forwiroh/releases/latest/download/install.sh | shWindows PowerShell:
irm https://github.com/trufae/forwiroh/releases/latest/download/install.ps1 | iexThe installers select x86_64 or arm64, pin the latest stable release, and verify
the archive against its CLI-SHA256SUMS before installing. The shell installer
uses ~/.local/bin (or $PREFIX/bin in Termux); PowerShell uses
%LOCALAPPDATA%\forwiroh\bin and adds it to your user PATH. Set
FORWIROH_INSTALL_DIR to choose another directory, or FORWIROH_VERSION=vX.Y.Z
to pin a version. No Rust compiler is needed.
Manual downloads are under Releases:
The Android app is available separately as forwiroh-android-debug.apk, built
from apps/android with arm64-v8a and x86_64 support. Install it directly on
Android 8+ or use adb install -r forwiroh-android-debug.apk. It uses Android's
automatic debug signing, with no release key configuration.
Smaller downloads are available as forwiroh-android-arm64-v8a-debug.apk for
arm64 phones and forwiroh-android-x86_64-debug.apk for x86_64 devices/emulators.
| CLI platform | Release assets | Requirements |
|---|---|---|
| Linux x86_64 / arm64 | forwiroh-{x86_64,aarch64}-unknown-linux-musl.tar.gz |
Static musl executables; glibc is not required. |
| macOS Intel / Apple Silicon | forwiroh-{x86_64,aarch64}-apple-darwin.tar.gz |
macOS 14+. |
| Android x86_64 / arm64 | forwiroh-{x86_64,aarch64}-linux-android.tar.gz |
Android 9+ (API 28), a shell such as Termux. |
| Windows x86_64 / arm64 | forwiroh-{x86_64,aarch64}-pc-windows-msvc.zip |
Windows 10/11. |
These are standalone CLI downloads. Android's native app and its VPN service
are separate. The Android CLI uses Iroh's public DNS fallback resolvers without
requiring a Java application context. All platforms support rootless TCP forwarding, reverse forwarding,
SOCKS, and use as an exit peer; CLI TUN creation is available only on Linux.
CLI builds use size optimization, full LTO, and stripped symbols. Linux, macOS
and Windows use min-size, which aborts on panic. Android retains unwinding
because its network-interface dependency catches the absence of a Java context.
See the size measurements.
import Forwiroh gives your application an async Swift API for pairing, peer
management, permissions, TCP forwards, reverse forwards, SOCKS, events, and VPN
packet transport. The package includes prebuilt core libraries: consumers do not
need Rust, binding generation, a bridging header, or a separate daemon.
Swift 6.2 or newer is required.
| SDK platform | Included architectures | Minimum |
|---|---|---|
| macOS | arm64 / x86_64 | macOS 14 |
| iOS | arm64 device; arm64 / x86_64 simulator | iOS 17 |
| Linux | arm64 / x86_64, glibc and musl | glibc 2.39 or musl |
| Android | arm64-v8a / x86_64 | API 28 |
| Windows | arm64 / amd64 (MSVC) | Windows 10/11; Swift 6.4 |
Download Forwiroh-<version>-swiftpm.zip from
GitHub Releases and unpack it, or
use a prepared checkout containing Artifacts/. In the sibling project's
pmai/MaiCore/Package.swift, add the dependency and attach its product to the
target that will own the endpoint:
dependencies: [
.package(path: "../../forwiroh"),
],
targets: [
.target(name: "YourTarget", dependencies: [
.product(name: "Forwiroh", package: "forwiroh"),
]),
]For example, on macOS, Linux, or Windows:
import Foundation
import Forwiroh
let state = URL.applicationSupportDirectory.appendingPathComponent("pmai/Forwiroh")
let node = try await Forwiroh.open(stateDirectory: state, name: "pmai")
let status = try await node.status()
print(status.id, status.peers)
// Once paired with "home", make its SSH service available locally.
let tunnel = try await node.forward(peer: "home", listen: "127.0.0.1:2222",
service: "127.0.0.1:22")
// Use localhost:2222, then stop the tunnel when finished.
try await node.stopTunnel(id: tunnel)
await node.close()Keep the endpoint alive for as long as the feature needs networking. Mobile callers supply a persistent 32-byte identity from Keychain/Keystore. Android also needs one-time JNI initialization and the certificate verifier's Java dependency. System VPN setup and background services remain the host application's responsibility. See the SwiftPM integration guide for pairing, events, mobile setup, lifecycle rules, and the standalone consumer example.
Binaries are generated output and are not committed to this source tree. A fresh
clone needs a maintainer build before SwiftPM can consume it. The
build and release instructions
and SwiftPM workflow produce Apple XCFrameworks,
Linux/Android/Windows static library bundles, and complete offline SwiftPM ZIPs in
dist/. Pushing a vX.Y.Z tag runs the complete build and test matrix, then
creates a GitHub release with SDK ZIPs, CLI archives for all eight targets, the
Android debug APK, the installers, and checksums for each set. Use the SwiftPM ZIP
asset for integration; GitHub's source archives do not contain the binaries.
Validation includes six Swift tests on macOS, Linux, and Windows, external SwiftPM consumers, an unpacked standalone package, iOS device/simulator linking, and Android native archive linking. Android Swift SDK builds are configured in CI; Android device runtime testing is still outstanding.
The Windows SwiftPM workflow also runs on
source pushes and can be dispatched independently. Its
Forwiroh-SwiftPM-windows-amd64 and Forwiroh-SwiftPM-windows-arm64 Actions
artifacts contain a ready-to-consume package for the corresponding architecture.
Use the CLI installer above, then run:
forwiroh serve --name homeTo build from source instead, install stable Rust (minimum 1.95), then:
git clone https://github.com/trufae/forwiroh.git
cd forwiroh
cargo install --path crates/forwiroh-cli --locked
forwiroh serve --name homeLeave that terminal running. Commands in other terminals talk to this daemon; they do not launch another copy of the identity.
By default, state lives in $XDG_STATE_HOME/forwiroh or
~/.local/state/forwiroh. To use a different directory, pass --state DIRECTORY
to every command, including serve.
On Windows, the default state directory is %LOCALAPPDATA%\forwiroh.
- Android: open
apps/androidin Android Studio, or follow the command-line build and APK installation instructions. The APK supports arm64 and x86_64. Start networking in the app. - iOS: open
apps/ios/Forwiroh.xcodeproj, configure your signing team and entitlements, then run on your device. See iOS signing/setup.
There is no App Store or Play Store distribution configured in this repository. Android CI uploads a debug APK; iOS CI produces unsigned bundles for validation.
In a second terminal on the home computer:
forwiroh pairScan the displayed QR in the phone app. Review and confirm the invitation, then
verify the requesting device identity in the home terminal and type y to approve.
Android can also accept a pasted invitation or display its own QR to another peer.
Invitations expire after five minutes and are single-use. If an invitation is
consumed or rejected, create a new one. Pairing can be cancelled with
forwiroh cancel-pair or the Android Cancel outgoing pairing control.
Suppose the home computer has SSH on 127.0.0.1:22. In the phone app, choose the
home peer and create a TCP forward:
| Setting | Value |
|---|---|
| Local listening port | 2222 |
| Remote destination / service | 127.0.0.1:22 |
| Listen on all interfaces | Off |
Now point an SSH client on the phone at 127.0.0.1, port 2222. Forwiroh carries
that TCP connection to SSH on the home computer. The destination's 127.0.0.1
means the home computer; the SSH client's 127.0.0.1 means the phone.
For a home web app, use a local port such as 8080 and the remote destination
where that app listens. Open http://127.0.0.1:8080 in a browser on the phone.
On iOS, switching away from Forwiroh suspends ordinary socket tunnels; use its
built-in TCP diagnostics for foreground checks or the separately configured VPN
for background network access. Android's notification keeps its service active.
Stop an individual tunnel in the app when finished. Android's Stop all networking button or notification Stop action closes all socket tunnels and VPN. On iOS, stop VPN separately in its VPN screen.
On the client, start another daemon with its own state directory:
forwiroh serve --name laptopIn another client terminal, accept the home invitation on standard input so its secret does not enter shell history. Paste the full invitation URI and press Return:
forwiroh pair --accept -
# Approve the request on the home computer, then:
forwiroh peers
forwiroh connect home
forwiroh forward home 2222:127.0.0.1:22
ssh -p 2222 user@127.0.0.1Names are case-sensitive and must be unique to select a peer by name. An endpoint ID identifies a peer unambiguously. To define a reusable destination name, run this on the machine hosting the service:
forwiroh allow laptop ssh 127.0.0.1:22Run this on the laptop to open a loopback listener on the home computer. Traffic
arriving at home port 8080 reaches the laptop's development server on port 3000:
forwiroh reverse home 8080:127.0.0.1:3000forwiroh socks home --listen 127.0.0.1:1080
curl --socks5-hostname 127.0.0.1:1080 https://example.com/Only applications configured to use that proxy send traffic through it. SOCKS supports TCP CONNECT, IPv4/IPv6 destinations and remote DNS. UDP ASSOCIATE is not implemented.
forwiroh status # peer connections and active tunnel IDs
forwiroh stop TUNNEL_ID
forwiroh disconnect home
forwiroh rename home home-server
forwiroh revoke home-server # removes trust and terminates sessions
forwiroh --versionQuiet TCP streams stay open while their QUIC connection is healthy; there is no five-minute application-idle cutoff. QUIC has a 20-second keepalive interval and a 60-second transport idle timeout. A stalled peer dial does not block connections to other peers, and shutdown cancels pending dials.
A disconnected TCP stream is never replayed. A new TCP connection may establish
a new Iroh session. For relay diagnostics, forwiroh serve --relay-only disables
direct UDP and requires relay transport.
Core events include connecting and connection_error with the peer ID.
disconnected includes the close reason and whether another connection to that
peer remains active. Forward/SOCKS tunnel_error events identify the peer and
tunnel, so clients can explain failures and decide when to reconnect.
Pair only devices you trust. By default, a paired peer can open TCP and SOCKS destinations and create reverse forwards on your device without another prompt. Requests are logged by the receiving device. Unpaired devices cannot open tunnels.
Policies describe what a peer may access on the device storing the policy.
To restrict a peer, save a policy such as this and apply it with
forwiroh policy PEER policy.json:
{
"restricted": true,
"services": {"ssh": "127.0.0.1:22"},
"reverse_ports": [8080],
"socks_networks": ["192.168.1.0/24"],
"socks_ports": [80, 443]
}Saving a policy closes existing sessions so removed grants take effect immediately.
With SOCKS restrictions enabled, both network and port must be granted; every
resolved address is checked before connecting to that numeric address. A saved
policy with no restricted field also uses the default open paired access.
Local forwarding listeners default to loopback. The mobile all-interfaces option
(0.0.0.0) lets other LAN devices use that port without local authentication;
enable it only when intended. SOCKS and reverse listeners remain loopback-only.
Use unprivileged listening ports, such as 2222, 8080 or 1080.
VPN needs more setup than TCP forwarding. The rootless exit on Linux or macOS uses ordinary TCP/UDP sockets; legacy Linux clients still require a provisioned TUN. Follow the VPN setup guide, then select the peer and routes in the phone's VPN screen.
The current transport uses QUIC datagrams with MTU 1100. Android uses VpnService;
iOS uses NEPacketTunnelProvider, offering ports-only or full IPv4/IPv6 routing.
Android leaves DNS on the system network and excludes Forwiroh's own transport
sockets from VPN.
macOS system/CLI VPN, SOCKS UDP and automatic VPN reconnect are not implemented. Chatmail integration is intentionally excluded; direct Iroh QR pairing is sufficient.
Native SwiftUI macOS and GTK4/Vala Linux apps live in apps/macos and apps/gtk.
They share the Rust core and provide peer pairing/approval with QR codes, TCP
forward/reverse/SOCKS controls, crypto/version information and a TCP test client.
See desktop build and run instructions.
The example service runs as your normal user; ordinary socket tunnels need no root:
mkdir -p ~/.local/state/forwiroh ~/.config/systemd/user
cp packaging/forwiroh.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now forwirohEdit the service if Cargo installs binaries outside ~/.cargo/bin or you use a
custom state directory. Configure user lingering separately for a headless server.
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
cargo build --workspace --locked
python3 scripts/cli-smoke.py
# Disposable Linux VM with network namespace/TUN privileges:
sudo python3 scripts/vpn-kernel.pyLocal core tests use real Iroh QUIC connections and TCP sockets with external relays disabled. CI additionally checks public-relay transport, Linux kernel TUN traffic, Linux/macOS CLI behavior, unsigned iOS builds and Android native builds, lint and emulator integration tests. Android build/test commands are in docs/android.md. Physical camera, mobile VPN and Wi-Fi/cellular transition testing remain separate validation tasks.
The workspace pins libc 0.2.188 while upstream Iroh dependencies migrate Apple mobile declarations removed in libc 0.2.190. The shared logo and its platform exports are documented in docs/assets.
