EmberNet Endpoint for Linux
The Linux endpoint is a headless daemon. There is no tray and no desktop app, so you operate it from a command-line tool (embernetctl) or a local web UI. It's built for facility gateways, edge compute nodes, Raspberry Pis running k3s, and any Linux host that needs to be on the EmberNet fabric.
Requirements
- A 64-bit Linux host (
x86_64orarm64) - Outbound HTTPS (port 443) connectivity
- Administrative (root) access to install
- A Microsoft account associated with your EmberNet tenant, for enrollment
Tested distributions include Debian 12, Ubuntu 20.04 / 22.04 / 24.04, and openSUSE Tumbleweed / MicroOS.
Install
One-shot script (recommended)
The quickest path. It detects your distribution, sets up the required tunnel dependencies, and installs the latest release for your architecture:
curl -fsSL https://embernet.ai/install-embernet-endpoint.sh | sudo bash
You can influence the script with environment variables set before you run it:
EMBERNET_VERSION=<tag>: install a specific version (default: latest)EMBERNET_NONINTERACTIVE=1: skip the post-install enrollment promptEMBERNET_REPO=<owner/repo>: pull from a fork instead of the default release repo
Package install
If you'd rather install a package directly, use the artifact that matches your host. Ask your EmberNet administrator for the download appropriate to your tenant.
| Host | Artifact |
|---|---|
| Debian / Ubuntu, x86_64 | embernet-endpoint_<version>-1_amd64.deb |
| Debian / Ubuntu, ARM64 (Pi 4/5, Jetson, Graviton) | embernet-endpoint_<version>-1_arm64.deb |
| openSUSE Tumbleweed, x86_64 | embernet-endpoint-<version>-1.x86_64.rpm |
| openSUSE Tumbleweed, ARM64 | embernet-endpoint-<version>-1.aarch64.rpm |
Install the .deb:
sudo apt install ./embernet-endpoint_<version>-1_amd64.deb
Install the .rpm:
sudo zypper install ./embernet-endpoint-<version>-1.x86_64.rpm
Either package drops the two binaries into /usr/bin/, installs the systemd service, creates the dedicated embernet system user and its directories, and enables the daemon. For containerized hosts (MicroOS and similar), a signed multi-arch OCI image covering linux/amd64 and linux/arm64 is also available; ask your administrator for the registry path and the cosign key to verify it against.
Enroll
After install the daemon is running, but no tunnels are configured yet. Enroll the host:
sudo embernetctl enroll
This walks the device-code flow: it prints a short code and a Microsoft login URL. Open the URL in any browser, sign in with your EmberNet Microsoft account, enter the code, and the wizard completes on its own. The tunnels come up and the host joins the fabric.
The daemon takes its device name from the host's hostname. If you need a different name in the dashboard, set the hostname before enrolling.
On headless hosts you can also enroll from the local web UI at http://127.0.0.1:8765/enroll.
The embernetctl CLI
embernetctl is the operator surface. It talks to the daemon over a Unix-domain socket at /run/embernet/control.sock (mode 0660, group embernet), so the user running it must be in the embernet group, or root. Add yourself once:
sudo usermod -aG embernet $USER
# Log out and back in for the group change to take effect.
The commands you'll use most:
embernetctl status # daemon + per-tunnel status, active path, health
embernetctl enroll # walk the device-code enrollment flow
embernetctl preflight # run the safety preflight (add --json for scripts)
embernetctl recover # exit quarantine after review
embernetctl panic # emergency: disconnect everything, enter quarantine
embernetctl version
embernetctl help
When you're diagnosing what the daemon has done to the host's network, three more are worth knowing:
embernetctl routes show # the routes the daemon currently claims
embernetctl firewall show # the current nft `inet embernet` table
embernetctl firewall reapply # idempotent rebuild of that table
embernetctl pretunnel show # the state snapshot taken before tunnels came up
embernetctl status is the single source of truth for what the daemon is doing. Run it first whenever something looks off.
The local web UI
For a browser instead of a CLI, open http://127.0.0.1:8765/ on the host. It offers the same Status, Diagnostics, Settings, and Enroll surfaces. The daemon listens on loopback only, never on the network, so to reach it from another machine, tunnel over SSH:
ssh -L 8765:127.0.0.1:8765 root@your-host
# Then open http://127.0.0.1:8765/ in your local browser.
Safety and quarantine
Linux endpoints often sit on factory floors next to equipment that does not tolerate mistakes. Before bringing tunnels up, the daemon runs a safety preflight. If a check fails, whether that's link state, routing sanity, or a host-firewall conflict, the daemon enters quarantine: no tunnel, firewall, or routing changes are made, and everything reports quarantined. The UI and embernetctl status keep working.
After you've reviewed what tripped it (embernetctl preflight --json) and fixed it, leave quarantine:
sudo embernetctl recover
To enter quarantine deliberately, the emergency hatch is:
sudo embernetctl panic
panic disconnects every tunnel and refuses to re-engage until you run recover. Use it when you'd rather have a disconnected facility than a wrongly-routed one.
Managing the service
sudo systemctl status embernet # service state + recent logs
sudo systemctl restart embernet # bounce the daemon
sudo journalctl -u embernet -f # follow live logs
Where things live
| Thing | Path |
|---|---|
| Daemon binary | /usr/bin/embernet-endpoint |
| Operator CLI | /usr/bin/embernetctl |
| systemd unit | /lib/systemd/system/embernet.service |
| Control socket | /run/embernet/control.sock |
| Persistent state | /var/lib/embernet/ |
| Config (operator-edited) | /etc/embernet/ |
| Logs | /var/log/embernet/ |
Uninstall
# Debian / Ubuntu
sudo apt remove embernet-endpoint # keep state in /var/lib/embernet
sudo apt purge embernet-endpoint # remove state too
# openSUSE
sudo zypper remove embernet-endpoint