Browse handbook

Operate Edge on a Linux VPS

Edge accepts Beacon's outbound QUIC connections and gives each configured service a TCP listener on the VPS. For websites, Nginx routes a visitor's HTTP request to the correct listener and handles HTTPS with Cloudflare. The Edge administrator owns enrollment, the VPS firewall, hostnames, public certificates, and recovery. An app owner runs Beacon and the local service and decides who can use that service. Beacon user guide

Choose addresses and firewall rules

Purpose OpenBYL deployment On a new deployment
Beacon's direct transport sotpyrk.cloud:7844 over UDP Use a DNS-only relay name or a reachable VPS IP. Permit UDP 7844 at the provider and host firewalls and outbound on the origin network.
Edge's private TLS identity edge.openbyl.com Issue Edge's private certificate for the server_name that Beacon verifies. This may differ from the transport address.
Public visitor HTTPS aburro.openbyl.com for Burro After HTTPS is provisioned, put a proxied A record on the app hostname pointing at the VPS IPv4 address. Use Full (strict) with a valid matching origin certificate.
Public web ingress VPS TCP 80 and 443 Let Nginx serve HTTPS and the ACME challenge. Apply Cloudflare source filtering to proxied application locations before rewriting client IPs.
Internal web upstream 127.0.0.1:18081 for Burro Bind each static HTTP route to a free loopback TCP port. Managed routes reserve ports in 20000–20999 on VPS loopback.

The orange-cloud visitor record puts proxied HTTP traffic through Cloudflare and its configured WAF rules. The direct Beacon UDP listener has a separate firewall and mutual TLS. The home router needs no inbound port forwarding. Cloudflare proxy status · Origin certificate requirements · OpenBYL DNS and firewall settings[1]

Bring up the first static website

This sequence is for a fresh Debian or Ubuntu VPS with systemd. The example uses identity studio, route web, local HTTP port 3000, and VPS listener 127.0.0.1:18080. Replace the example names with your own. Detailed installation commands for each machine are in the linked runbooks.

  1. Issue identities on the trusted enrollment workstation. With Python and OpenSSL installed, use scripts/pki.py ca to create an issuer, pki.py edge for Edge's TLS name, and pki.py beacon for the client. Copy the appropriate TOML template into each role's bundle. Edit the Beacon transport address, TLS name, and [routes]. In Edge, set the client fingerprint printed at issuance, the route's owner, and its listener. Keep the signing key in protected enrollment storage. Enrollment commands and templates[2]
  2. Build and install Edge. Obtain the checkout from the maintainer's repository URL or Git bundle. On a compatible Linux machine with stable Rust and a native C toolchain, run cargo build --release --locked -p edge --target-dir target. Transfer the executable, unit, and Edge bundle privately. The supplied unit runs as openbyl-edge. Install /usr/local/bin/edge, the unit in /etc/systemd/system/, and protected credentials under /etc/openbyl-edge/. Use the runbook's ownership and modes so the service can read its key and only administrators can modify it. Fetch the source[3] · First installation commands[4]
  3. Validate and start the service. Run the checks below on the VPS. Expect an active service, a UDP listener on 7844, and a TCP listener bound to 127.0.0.1:18080. Enable the provider and host firewall rules for this deployment. A successful --check verifies local configuration and TLS material. Starting the service tests the actual listener binds. Service unit[5]
sudo -u openbyl-edge /usr/local/bin/edge --config /etc/openbyl-edge/edge.toml --check &&
  sudo systemctl daemon-reload &&
  sudo systemctl enable --now openbyl-edge
systemctl is-active openbyl-edge
sudo ss -lunp 'sport = :7844'
sudo ss -lntp 'sport = :18080'
  1. Connect the client and test the listener. Give the client owner their four-file enrollment. Once Beacon shows Connected, request the actual app from Windows, then the listener from the VPS. For this example run curl.exe http://127.0.0.1:3000/ on Windows and curl --max-time 10 -H 'Host: app.example.net' http://127.0.0.1:18080/ on the VPS. Expect the app's identifiable response at both.
  2. Publish over HTTPS. Map the intended Nginx virtual host to that listener. On a new site, use the HTTP challenge, TLS certificate, Cloudflare allowlist, and proxy-status sequence in the Debian/Ubuntu runbook. Run sudo nginx -t before reload, verify certificate renewal, and request a known, uncached app response from another network. Verify sign-in where the app requires it. First HTTPS site[6]

Enroll and remove devices

With Edge Accounts enabled in 0.3.0, issue one invitation per person for initial registration. Each laptop links from Beacon through a short-lived browser approval code. Edge loads the resulting device certificate grant while it is running. The account owner can revoke a lost laptop independently. The publisher requires visitor credentials by default on these new account routes. Older manual profiles keep their existing route policies. Account setup and operations[7] · Connect a laptop

Issue one client certificate per machine. Edge associates the leaf certificate fingerprint with a named owner. A new connection using the same fingerprint replaces that identity's current session. For static routes, add the named owner under [[beacons]] and use that owner in the corresponding [[routes]] entries. Edge configuration template[8]

For dashboard publishing on OpenBYL, enable the publisher first, then configure a top-level device_dir = "devices.d". On the trusted Windows enrollment workstation, the following command uses an existing issuer and a fresh output directory. It generates both a workstation profile with the OpenBYL addresses and an edge-grant.toml with a fingerprint and hostname prefix. For a different domain, prepare the client profile using your actual relay, TLS name, zone, origin IPv4, and grant prefix. OpenBYL enrollment tool[9]

$enrollment = Join-Path $env:LOCALAPPDATA 'OpenBYL\TunnelEnrollment'
$bundle = Join-Path $enrollment 'alex-laptop'
py -3 scripts/pki.py profile (Join-Path $enrollment 'issuer') $bundle alex-laptop

Install only the grant on Edge as /etc/openbyl-edge/devices.d/alex-laptop.toml. Deliver the four profile and identity files privately to the device owner. Validate Edge and restart it in a maintenance window. With the example grant, the user can publish alex-laptop-notes.openbyl.com. Scoped grants receive eight managed hostnames each, subject to 64 total Edge reservations. Prefixes must be disjoint. Publishing setup and exact grant installation[10]

Rotate or revoke. Check certificate expiry with openssl x509 -in identity.pem -noout -enddate. The project issuer creates 365-day leaf certificates. For a rotation, stage the new matching cert and key on the client, replace the fingerprint for the same device on Edge, validate, then restart both. For a revoked scoped device, disable its .toml grant, remove any static routes that still refer to it, validate, and restart Edge. For an inline identity, remove its pin, routes, and publishing grant. Preserve other owners' assignments. Retire the public site separately and avoid reusing an old device name for a new owner. Rotation and revocation[11]

Publish or retire a site

Choice Operator action
Static website or raw TCP Configure a matching route name at Edge and Beacon, validate both, and restart the affected processes. Map the web hostname in Nginx. For direct TCP, expose only the intended listener to the intended visitors and secure that protocol at the origin. Static TCP example[12]
Add Route from a Windows PC Install the Python 3.11+ publisher service and socket, Nginx configuration, Certbot and its existing ACME account, and the Edge publishing state-directory drop-in. Configure matching zones and the device grant. Validate both configs, then restart once. New hostname requests can then take effect while Edge runs. Publisher installation[13]
Manual or automatic DNS For manual DNS, add the exact proxied A record shown in Beacon. For automatic DNS, the VPS helper needs a token limited to DNS editing in the chosen zone and a root-only token file. Resolve any conflicting DNS record before retrying. DNS provisioning instructions[14]

An account owner can turn off the original device-prefixed address from Beacon once a short address is ready. New visits to the original address receive HTTP 403. Edge retains its tunnel assignment so short addresses continue working. Manage an account route

Decommission an entire managed site during maintenance. The administrator and the device owner remove the site together.

  1. Record the owner, hostname, local port, and reserved Edge port. Back up the client request file and server state. Exit the owning Beacon and remove only the matching request object from its beacon.toml.routes.json array. A saved request can recreate the site when the client reconnects. Beacon's saved requests[15]
  2. Stop the publisher socket and service. Retire the matching helper record, Nginx virtual host, DNS record, and certificate renewal. To prevent future republication, add the retired label to reserved_labels after removing the helper record. Preserve the Edge reservation so an old upstream port cannot be assigned to another site. Publisher policy[16] · Helper validation[17]
  3. Test and reload Nginx before restarting the publisher socket. Reopen Beacon and verify that the hostname stays retired and another route still works. Retirement and server recovery[18]

Diagnose an incident

Observation Narrow the fault
No Beacon connection Check systemctl is-active openbyl-edge, the UDP listener, and sudo journalctl -u openbyl-edge -b -n 80 --no-pager. Confirm the direct relay address, firewalls, client egress, clocks, private CA, TLS name, and enrolled fingerprint.
Beacon connected, site returning 502 Test the app on the origin PC, then the corresponding Edge loopback listener, then the public hostname. If the VPS listener works, inspect the Nginx upstream and site certificate. If it fails, inspect ownership, Beacon's target and counters, origin availability, and stream limits.
Waiting for DNS or Setting up HTTPS Inspect systemctl status openbyl-publisher.socket, sudo journalctl -u openbyl-publisher.service -n 50, and sudo nginx -t. Check the exact hostname, proxy status, ACME challenge, certificate, and site's HTTPS reachability.
Burro loads but a private action fails Check the app's session, allowed origin, cookie handling, and the Burro-specific Nginx rules. Use /api/health for routing and unauthenticated /api/status for visitor authentication. Burro proxy configuration[19]
Only edge.openbyl.com/ works Its Nuxt guide is hosted on the VPS. Compare a fresh nonce and proof from the dedicated /_tunnel/probe/ endpoint with its Windows origin to test the tunnel. Exact end-to-end check[20]

Update, roll back, and recover

Before a server change, inventory active owners and sites and take a protected backup of the matching binary, unit/drop-ins, /etc/openbyl-edge/, Edge reservations, helper configuration and state, and Nginx and Certbot state. Record the corresponding DNS names and records. Each client owner should back up its own profile, key, saved requests, and stopped preference. Backup paths[18] · Beacon profile locations

Validate staged Edge configuration with the matching executable and credentials as the service user. Validate Nginx before reloading. Restart Edge during the agreed maintenance window. This interrupts all active streams, and enabled Beacons reconnect automatically. If the change fails, restore the matching previous files, validate again and restart. When recovering managed websites, restore reservations, helper state and frontend mappings together. Verify the local origin, its Edge listener, and a fresh public response for each affected route before declaring service restored.

Repository references

  1. deploy/README.md#dns-and-listeners
  2. README.md#enroll-one-edge-and-one-beacon
  3. README.md#get-the-source
  4. README.md#install-edge-on-linux
  5. deploy/openbyl-edge.service
  6. deploy/README.md#first-https-site-on-debian-or-ubuntu
  7. deploy/accounts/README.md
  8. examples/edge.toml
  9. scripts/pki.py
  10. deploy/PUBLISHING.md#enroll-another-person-or-device
  11. deploy/README.md#changes-rotation-and-diagnosis
  12. deploy/README.md#publish-a-raw-tcp-service
  13. deploy/PUBLISHING.md#enable-publishing-on-an-existing-edge-installation
  14. deploy/PUBLISHING.md#optional-automatic-dns
  15. crates/beacon/src/publish.rs
  16. deploy/openbyl-publisher.example.toml
  17. deploy/publisher.py
  18. deploy/PUBLISHING.md#recovery
  19. deploy/burro.nginx.conf
  20. README.md#operate-and-verify