Burrowee Docs

Appearance

Install edge ​

Install burrowee-edge to run your own self-hosted relay — on a machine inside your LAN for fast local hops, or on a public host (a VPS at edge.example.com, say) under your own domain. An edge is account-bound: it carries only your own gateways and is managed from the console.

sh
curl -fsSL --proto '=https' --tlsv1.2 https://release.burrowee.com/edge/install.sh | sh

The installer detects your OS and architecture, downloads the latest edge release, verifies it (minisign signature, then SHA-256 — see the install overview for the full chain), and installs four binaries (default ~/.local/bin; see Installing with sudo for the root path):

  • burrowee — the universal dispatcher; burrowee edge … runs whichever of the two binaries below the verb needs.
  • burrowee-edge — the relay daemon: serves the edge and handles run/update/version.
  • burrowee-edge-cli — every other edge verb: bootstrap, nginx, mode, cert, bridge, service, status, doctor, config, push, … The dispatcher routes these here automatically.
  • burrowee-edge-updater — a standalone agent that applies console-pushed updates. A sudo install wires it up as its own managed service alongside the edge; the default non-root install just drops the binary on disk without a service (see Installing with sudo).

If ~/.local/bin is not on your PATH, the installer says so and prints the line to add:

sh
export PATH="$HOME/.local/bin:$PATH"

Installing with sudo ​

Run the same one-liner with sudo (curl … | sudo sh) and the installer takes the root path instead: binaries go to /usr/local/bin, and it writes + enables a managed system service — a systemd system unit on Linux, a launchd LaunchDaemon on macOS — running burrowee-edge run, with its config home at /root/.burrowee/edge. Re-running the same sudo one-liner later is an in-place update: it replaces the binaries and restarts the service. Pairing is still a separate step — the installer prints it as your next command:

sh
sudo burrowee edge cli bootstrap <blob> <pin>

Without sudo, you get the historical unprivileged install: binaries under $HOME/.local/bin, config under ~/.burrowee/edge, and no managed service until you set one up yourself (see First run below). The non-root installer prints a note that a managed system service needs a re-run with sudo.

First run ​

On a fresh non-root interactive install (a real terminal, not CI), the installer offers to set the edge up on the spot:

Set up now? Paste the setup blob + PIN from the console (Enter to skip).
blob>

Mint the edge relay in the console first — that is what produces the setup blob and PIN. Paste both at the prompt and the installer runs burrowee edge cli bootstrap for you. Press Enter to skip and do it later:

sh
burrowee edge cli bootstrap <blob> <pin>

Two cases where the prompt does not appear:

  • Already set up — if ~/.burrowee/edge/identity (or console.json) already exists, re-installing never re-prompts; the binaries are simply updated in place.
  • No terminal (CI, a provisioning script) — the installer just prints the bootstrap command as your next step.

A root (sudo) install skips this prompt entirely — see Installing with sudo.

Platform notes ​

  • Linux (typical VPS): a preflight step tries to install minisign, unzip, curl, and (for the default nginx-fronted topology) nginx + its stream module for you via your package manager, using root if available; if that's not possible, install them yourself (apt-get install minisign unzip or your distro's equivalent) — verification is mandatory and the installer aborts without minisign/unzip. Skip preflight with BURROWEE_SKIP_PREFLIGHT=1, or skip just the nginx group with BURROWEE_SKIP_NGINX=1.
  • macOS: every release is verified via minisign + SHA-256 before install (see the install overview); the binaries themselves are ad-hoc signed, not Developer ID signed or notarized, but since they arrive via curl | sh rather than a browser download, macOS never sets the quarantine attribute in the first place — the installer strips it defensively anyway. If you ever place a binary on PATH by hand and macOS blocks it: xattr -d com.apple.quarantine ~/.local/bin/burrowee-edge.
  • nginx fronting is the default topology for a running edge, but it is configured after install, during setup: sudo burrowee edge nginx install writes the SNI/ssl_preread host-front stream config — TLS terminates inside burrowee-edge itself, so nginx never touches certificates — and reloads nginx. The legacy nginx apply path instead generates the edge's self-signed LAN certificate and configures TCP passthrough directly. Nothing to do at install time beyond the preflight package install above.

Next step ​

Pair the edge to your account, approve it, and start serving: Edge overview.