Browse handbook

What the tunnel gets right and where it falls short

The design fits a small set of enrolled devices publishing services through one operator-managed VPS. Burro is a good example when the laptop can stay awake, reach the VPS over UDP, and enforce its own visitor access policy. A service that must survive laptop sleep, relay maintenance, or the loss of one site needs additional availability measures. The relay's device registry holds one active session for each fingerprint. Session registry[1] · Security report

What works well

Strength Evidence and practical value
Applications can keep their existing sockets The process test carries HTTP and eight concurrent binary transfers, including a server that speaks first and replies after the visitor finishes sending. This exercises real sockets, half-close and byte counts. A local TCP application needs no tunnel SDK. Process test[2]
Identity is assigned at the relay A CA-issued certificate still needs a configured fingerprint. Two enrolled devices can each have a route called web and receive their own traffic. The process test covers this distinction, the offline-device case and three TLS or authorization failures. Process test[2] · Edge configuration[3]
An intentional stop survives relaunch An operator can take a service offline while continuing to use the dashboard. The process test keeps a visitor connected while issuing Stop, checks that the stream closes, relaunches Beacon, starts it again, and checks a fresh response. Process test[2]
A publishing retry preserves the upstream port Edge writes its reservation before the helper call. The Unix test loses a helper response, restarts Edge, retries the request and checks the port and owner. This prevents an old Nginx virtual host from silently switching to a different app. Reservation implementation and test[4]
The public site and the laptop can be checked independently The VPS guide, the nonce-bearing proof route and Burro's health endpoint answer three different operational questions. That narrows an outage to web ingress, tunnel forwarding or the application. Field guide routing[5] · Verification steps[6]

Where operators will encounter limits

Limit confirmed in this version Consequence for a deployment
The carrier requires outbound UDP. One Edge owns the listeners and sessions. A network that blocks the configured UDP destination cannot connect. A relay restart drops every active visitor stream. When connectivity returns, Beacon can serve new requests. Applications must decide how to retry interrupted writes, streams or downloads. Beacon dial and retry loop[7] · Edge lifecycle[1]
The default stream budget is 128 per device across its routes. A long-lived stream occupies a slot until it closes. At the Edge limit the next TCP connection is dropped. A busy app can therefore make another route on the same Beacon appear unavailable. Size limits with the intended workload and test what visitors see at saturation. Edge admission[1] · Beacon defaults[8]
Device enrollment and static routes load at startup. Adding a static listener, replacing a fingerprint or revoking a grant requires a validated Edge restart. Clients reconnect after the restart. Tracked publishing state preserves existing hostname ownership, so retiring a device also requires handling its old web and DNS configuration. Edge startup[1] · Device enrollment and retirement[9]
Retiring an entire published route still requires an operator. Beacon owners can edit a local port or turn off an account route's original address after claiming a short address. Neither operation releases the reserved listener. Retained reservations count toward the 64-host deployment limit. A prefix-scoped device has eight slots. Edit a saved route · Retire a site
Beacon's counters measure bytes read from and written to local application sockets. They reset with the process and exclude QUIC overhead, retries at the network layer, frontend traffic and other VPS services. Use provider transfer data for the VPS allowance. Use Beacon's per-route counters to see which local apps are moving payload. Telemetry implementation[10]
Website readiness, tunnel connectivity and visitor login have different owners. An HTTPS-ready site can still return a gateway error if the app stops, or reject a login if the public hostname conflicts with its policy. Burro uses a dedicated virtual host with specific host, origin, cookie and streaming rules. New apps get the generic publisher configuration and need their own access checks. Generic site generation[11] · Burro frontend[12]

Evidence to collect before making release claims

The repository's transport check exercises separate processes on loopback. The publishing smoke test uses real Beacon and Edge binaries with a stand-in for the privileged helper. Helper tests exercise the publishing workflow in isolation. These are appropriate checks for regressions in protocol and state handling. Production DNS, ACME issuance, real network loss and the intended concurrency are separate acceptance tests. Transport smoke[2] · Publishing smoke[13] · Helper tests[14]

Claim to evaluate Evidence that would support it
“The VPS can serve our launch traffic.” Record concurrent short requests and long-lived streams at the target mix, throughput in both directions, errors, latency, CPU and memory at Edge. Measure provider transfer over the same interval. A successful loopback demo cannot supply a KVM bandwidth forecast.
“A new customer can publish from Windows.” On a clean supported PC, install the release artifact, import a fresh device profile, publish a disposable hostname, and exercise the real app and its login through the intended HTTPS frontend. Record package identity, Windows version and observed results.
“We can recover or revoke safely.” On an isolated deployment, restore matching Edge, helper, frontend and Beacon state. Check one existing site's owner and response, then revoke a test device while verifying a second device keeps its original hostname. State to restore[15]

For everyday use, follow the Beacon guide. For installation and verification on the VPS, follow the Edge guide.

Repository references

  1. crates/edge/src/main.rs
  2. scripts/demo.py
  3. crates/edge/src/config.rs
  4. crates/edge/src/publishing.rs
  5. deploy/field-guide.nginx.conf
  6. README.md#operate-and-verify
  7. crates/beacon/src/tunnel.rs
  8. crates/beacon/src/config.rs
  9. deploy/PUBLISHING.md#enroll-another-person-or-device
  10. crates/beacon/src/status.rs
  11. deploy/publisher.py
  12. deploy/burro.nginx.conf
  13. scripts/publish_smoke.py
  14. scripts/test_publisher.py
  15. deploy/PUBLISHING.md#recovery