Skip to content
trufaePublic

About

Port Forwarding and VPN over IROH

Resources

Stars

18 stars

Watchers

0 watching

Forks

Repository files navigation

Forwiroh — two linked endpoints

Forwiroh

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.

What can I do with it?

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.

Platforms

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.

Install the CLI

Nix / NixOS

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 -- --help

To build the package from a local checkout:

nix build .#forwiroh

For 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 build

Linux, macOS, and Android (Termux):

curl -fsSL https://github.com/trufae/forwiroh/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/trufae/forwiroh/releases/latest/download/install.ps1 | iex

The 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.

Embed with SwiftPM

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.

Quick start: phone → home computer

1. Install the home daemon

Use the CLI installer above, then run:

forwiroh serve --name home

To 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 home

Leave 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.

2. Install the phone app

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.

3. Pair once

In a second terminal on the home computer:

forwiroh pair

Scan 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.

4. Open a service

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.

Use a Linux or Mac client

On the client, start another daemon with its own state directory:

forwiroh serve --name laptop

In 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.1

Names 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:22

Reverse forward

Run 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:3000

SOCKS5

forwiroh 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.

Inspect and stop

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 --version

Quiet 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.

Trust and access restrictions

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.

Optional VPN setup

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.

Desktop apps

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.

Start at login on Linux

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 forwiroh

Edit the service if Cargo installs binaries outside ~/.cargo/bin or you use a custom state directory. Configure user lingering separately for a headless server.

Development and testing

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.py

Local 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.

About

Port Forwarding and VPN over IROH

Resources

Stars

18 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages