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.

curl -fsSL --proto '=https' --tlsv1.2 https://release.burrowee.com/edge/install.sh | sudo 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 into the root-owned exec root /usr/local/burrowee/bin — the only install destination; there is no per-user path, which is why the one-liner runs under sudo:

• burrowee — the universal dispatcher; burrowee edge … runs whichever of the edge binaries owns the verb.
• burrowee-edge — the relay daemon: serves the edge (run, 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 — the update agent behind burrowee edge update and console-pushed updates. Its service unit is installed alongside the edge's but console pushes stay opt-in (burrowee edge push allow).

Where everything lands

The install is machine-owned, not per-user:

What	Where
Binaries	/usr/local/burrowee/bin (root-owned; not on PATH — see below)
Config (identity, enrollment, config)	/usr/local/burrowee/etc/edge
Runtime data (logs, stats, cover pages)	/usr/local/burrowee/var/edge
Service units	com.burrowee.edge + com.burrowee.edge.updater — LaunchDaemons on macOS, system units (/etc/systemd/system/burrowee-edge.service) on Linux

Nothing is written to /usr/local/bin, and /usr/local/burrowee/bin is on nobody's PATH, so a successful install ends by printing the line that adds it for your login shell. Because the edge is one machine-owned copy shared by every account on the host, the permanent entry it names is the system-wide profile (/etc/paths.d/burrowee on macOS, /etc/profile.d/burrowee.sh on Linux) rather than your own — the installer prints the sudo tee line and never applies it. Run it, or use the full path (/usr/local/burrowee/bin/burrowee edge …) until you do. Details and the per-shell block: Put the exec root on PATH.

~/.burrowee/edge is used only on a host with no system install (an unprivileged development run). Every burrowee edge command takes --home <dir> to name a different config root; the data root always follows it, so one --home always means exactly one tree.

Upgrading from a pre-0.2.0 install

Re-running the install one-liner (or burrowee edge update) also runs the release's migration ladder:

• An adoption step copies a pre-0.2.0 per-user tree (~/.burrowee/edge) into the machine-owned roots above — copies, never moves, and the installer doesn't swap binaries or write units unless the migration can complete. The verified source tree is renamed aside with a .bak.<timestamp> suffix and a one-mv recovery line is printed. To re-run or repair an adoption by hand there is a dedicated verb: burrowee edge migrate --from <dir> (with --force to overwrite a destination adopted from the wrong source).
• A sweep removes stale copies of the binaries that would shadow the fresh ones: pre-0.2.0 per-user binaries (under ~/.local/bin), which it asks about per file, and the 0.2-era binaries and symlinks an earlier installer left in /usr/local/bin. After removing one it tells you how to clear your shell's stale command hash (hash -r, or just open a new shell).

There is also a hosted upgrade one-liner that re-installs and then force-runs every migration the release carries — the repair for a host that reached a newer version without its older migrations running (hand-placed binaries, a missing/wrong version anchor, or a rebuilt binary on the same version):

curl -fsSL --proto '=https' --tlsv1.2 https://release.burrowee.com/edge/upgrade.sh | sudo sh               # force the whole shipped ladder
curl -fsSL --proto '=https' --tlsv1.2 https://release.burrowee.com/edge/upgrade.sh | sudo sh -s -- 0.2.0   # force the 0.2.0-and-newer migrations

The optional argument is the inclusive migration floor ("assume this host is below it") — it selects which migrations are forced and never changes which release installs (always the newest). Details: Upgrading.

First run

Pairing is a separate step after install. Mint the edge relay in the console first — that is what produces the setup blob and PIN — then run the command the installer prints as your next step:

burrowee edge cli bootstrap <blob> <pin>

This works the same in CI or a provisioning script — the installer needs no terminal and just prints the bootstrap command. Re-installing over an already-paired edge never touches the enrollment; the binaries are simply updated in place.

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 /usr/local/burrowee/bin/burrowee-edge. There is no macOS preflight package install — Homebrew refuses to run as root, so the installer never installs nginx for you here, and it never runs as root itself either. Install nginx yourself first (brew install nginx, then sudo brew services start nginx — the sudo is what makes it a system LaunchDaemon instead of a per-user LaunchAgent that starts nothing at headless boot). burrowee itself runs as root here, and it can resolve, test, reload and manage that Homebrew nginx under its root-equivalent owner rule — root executes a binary out of a user-owned prefix only when every account that can write that prefix could already become root. See nginx on macOS for the three supported layouts, what the rule refuses and how to fix it, and why the config burrowee writes lives in its own root-owned tree rather than Homebrew's.
• nginx fronting is the default topology for a running edge, but it is configured after install, during setup: bootstrap (or a later 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. Nothing to do at install time beyond having nginx already in place (Linux: the preflight above; macOS: the bullet above).

Next step

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