Skip to main content

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, and any Linux host that needs to be on the EmberNet fabric.

Requirements​

  • A 64-bit Linux host (x86_64 or arm64)
  • Outbound HTTPS (port 443) connectivity
  • Administrative (root) access to install
  • An enrollment code from your tenant's admin (EmberCORE, Enrollment codes), or an identity provider account associated with your EmberNet tenant

Tested distributions include Debian 12, Ubuntu 20.04 / 22.04 / 24.04, and openSUSE Tumbleweed / MicroOS.

Install​

The quickest path, and it needs one thing: an enrollment code from your tenant's admin (in EmberCORE, under Enrollment codes). A code works once, expires, and carries your tenant, so you never handle a shared secret. Run:

curl -fsSL https://embernet.ai/install-embernet-endpoint.sh | sudo EMBERNET_ENROLL_CODE=<code> bash

The script installs what the endpoint needs, enrolls the host with your code, starts the endpoint as a service, and waits until Flux reports connected. The endpoint follows the stable channel and updates itself, so there is nothing to upgrade by hand. Each step skips what is already done, so if a run stops, fix the cause and run it again.

You can set these before you run it, or pass the matching option:

  • EMBERNET_ENROLL_CODE=<code> (--code): the enrollment code. --code-file <path> reads it from a file instead.
  • EMBERNET_DEVICE_NAME=<name> (--name): the device name shown in EmberCORE. The default is the host's hostname.
  • EMBERNET_CHANNEL=stable|beta (--channel): the update channel. An endpoint always follows a channel and is never pinned to one version.
  • --tenant-id <id>: optional, since the code already names the tenant. A code from a different tenant is refused.
  • --no-enroll: install and start the endpoint without enrolling it.
  • --no-watchdog (EMBERNET_NO_WATCHDOG=1): for cloud VMs whose gateway drops ping.

The host needs root access and outbound HTTPS to EmberNet. Ask your administrator for the exact addresses your firewall must allow.

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.

HostArtifact
Debian / Ubuntu, x86_64embernet-endpoint_<version>-1_amd64.deb
Debian / Ubuntu, ARM64 (Pi 4/5, Jetson, Graviton)embernet-endpoint_<version>-1_arm64.deb
openSUSE Tumbleweed, x86_64embernet-endpoint-<version>-1.x86_64.rpm
openSUSE Tumbleweed, ARM64embernet-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 installs the endpoint as a service and starts it. For containerized hosts, a signed container image for x86_64 and ARM64 is also available; ask your administrator for it.

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 sign-in URL. Open the URL in any browser, sign in with your identity provider, 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 EmberCORE, set the hostname before enrolling.

On headless hosts you can also enroll from the endpoint's local web screen (see below).

The embernetctl CLI​

embernetctl is the operator surface. Run it as root, or as a user you have added to the embernet group:

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, which connection is active, health
embernetctl enroll # walk the device-code enrollment flow
embernetctl preflight # run the safety preflight
embernetctl recover # exit quarantine after review
embernetctl panic # emergency: disconnect everything, enter quarantine
embernetctl version
embernetctl help

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

Uninstall​

# Debian / Ubuntu
sudo apt remove embernet-endpoint # keep its state
sudo apt purge embernet-endpoint # remove state too

# openSUSE
sudo zypper remove embernet-endpoint

Next steps​

  • Read the Overview for how the endpoint fits the platform
  • Manage enrolled endpoints from EmberCORE
  • See Flux for the endpoint's primary transport, and ArcNet for the network interface whose traffic rides Flux