Browse handbook

Project Tunnel handbook

Account pilot · Beacon and Edge 0.3.1. Sign in once on each laptop, publish its local apps, and choose which short address Beacon opens. You can change a saved route’s local port from the hosting laptop. Connect a laptop · Edit a route · Open Edge Accounts

The original security review covers Beacon and Beacon Desktop 0.2.2, Edge and tunnel-core 0.2.0. The account pilot adds device sign-in and private routes. Its verification used the live VPS, the proxied wildcard, and two independent Beacon instances. Account pilot results

Beacon gives an app on your computer a public address. It calls out to Edge on your VPS. When a visitor arrives at the VPS, Edge sends that connection back to Beacon, which opens the app's local port. You can keep Burro on 127.0.0.1:4747, visit it at aburro.openbyl.com from a phone, and leave your home router closed to inbound connections. Burro decides who can sign in. Follow a Burro request

Find your task

I want to… Open this page
Install Beacon, publish a local app, use the Windows tray, or stop the tunnel Run Beacon on Windows
Install Edge, set up Cloudflare, enroll another PC, rotate a key, or retire a hostname Operate Edge on a Linux VPS
Understand what crosses the internet, where TLS ends, and who owns each route How a request reaches Beacon
Decide whether the system fits a workload, including outages and bandwidth limits What the tunnel gets right and where it falls short
Review access boundaries, security findings, mitigations, or respond to a lost device Security review
See exactly what passed, what failed, and what would justify a release candidate Release evidence and decision

Try the tunnel locally

Ask the maintainer for the repository URL or a Git bundle. For a bundle, run git clone --branch main project-tunnel.bundle project-tunnel. In the checkout, with Rust, a native C toolchain, Python 3.11+ and OpenSSL installed, run the following in PowerShell. On Linux, use python3 in place of py -3. Source and prerequisites[1]

cargo build --locked --target-dir target
py -3 scripts/demo.py --dashboard-port 0

The demo starts a local Edge, Beacon, and web origin with disposable certificates. Open the printed Web through Edge URL, refresh it, and watch the stream count in the demo dashboard. The random dashboard port lets the demo run beside your installed Beacon. Press Ctrl+C to stop the demo. Local demo guide[2]

What “working” looks like

Observation What it tells you
Beacon shows Connected Edge accepted this device's certificate and enrollment.
A newly published route shows Ready The public HTTPS frontend answered the publisher's challenge.
A phone receives the expected, fresh app response That hostname reaches a working application.
A signed-out visitor is denied a private action, and the intended user can perform it The app's visitor policy works for that action.

For OpenBYL, the homepage at edge.openbyl.com lives on the VPS and stays available when the laptop goes offline. Burro and the optional proof service have different routes and different local processes. A healthy homepage alone cannot establish that either is reachable. Layer-by-layer troubleshooting

Release posture. The current evidence supports a pilot with trusted operators and enrolled devices. Public Windows distribution still needs a signed package tested on a clean PC. Allowing unrelated users to publish under a shared domain needs a separate browser-isolation decision. The release record gives the proposed gates and names the evidence still missing. Release decision

Repository references

  1. README.md#get-the-source
  2. README.md#try-it-locally