Edge install

ongrid-edge is a single static Go binary plus four plugin subprocesses. There is no compose, no DB, no inbound port — one outbound TCP connection to the frontier broker, and one outbound HTTPS connection per plugin to the data plane.

The canonical install is curl-pipe from the manager's /install.sh endpoint. The manager serves the installer, the agent binary, the plugin binaries, and the upgrade hook from the same /edge/ static path, so the only thing the operator needs is a network route back to the manager.

Prereqs

The target host needs:

• Linux on amd64 or arm64. macOS edges work but lose the logs
  • hostmetrics plugins (upstream Grafana / node_exporter don't ship darwin builds); see macOS edge dev.
• systemd for service supervision.
• outbound TCP/40012 to the manager (control plane).
• outbound TCP/443 to the manager (data plane — logs + traces push).
• curl and root (the installer re-execs via sudo if needed).
• No specific RAM/disk floor — the agent is well under 50 MB RSS plus whatever the plugin subprocesses use.

Create the edge in the UI

1. Sign in to the manager.
2. Edges → New edge.
3. Name it (e.g. prod-web-01). Optional description.
4. Press Create.

The detail page now shows:

• Access key (AK_...) — server-generated, identifies the edge.
• Secret key (SK_...) — shown once. Lose it and you rotate.
• Install command — a curl ... | sudo bash -s -- one-liner with the access key, secret key, edge tunnel endpoint, and HTTP endpoint baked in.

Capture the secret key NOW

The secret key is shown once. If you lose it before installing, delete and re-create the edge — it's safer than digging through DB backups.

Install command

Copy the one-liner from the UI. It looks like:

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=203.0.113.10:40012 \
    --server-http-addr=203.0.113.10:443

The flag semantics:

• --access-key / --secret-key — auth material for the geminio tunnel. The agent presents these on dial; frontier asks the manager's edgeauth to verify.
• --server-edge-addr — host:port for the control plane. Always 40012 unless you've overridden it.
• --server-http-addr — host:port for the data plane and binary download. The same host:port your browser uses to reach the UI. Plain host is allowed (defaults to 443). The installer downloads its binary from https://<http-addr>/edge/ongrid-edge-<os>-<arch>.

Run it. The installer re-execs via sudo if you didn't already.

What gets dropped on disk

/usr/local/bin/
  └── ongrid-edge                       # the agent binary (mode 0755)

/usr/local/lib/ongrid-edge/
  ├── apply-pending-upgrade.sh          # ADR-024 ExecStartPre hook (mode 0755)
  ├── promtail                          # plugin: logs (Loki push)
  ├── otelcol-contrib                   # plugin: traces (OTLP push)
  ├── node_exporter                     # plugin: hostmetrics
  └── process_exporter                  # plugin: procmetrics

/etc/ongrid-edge/
  └── ongrid-edge.env                   # access/secret keys (mode 0640,
                                        # owner root:ongrid-edge)

/etc/systemd/system/
  └── ongrid-edge.service               # systemd unit

/var/lib/ongrid-edge/                   # StateDirectory, created at start
  └── .upgrade/                         # staged bundles, markers

/var/log/ongrid-edge/                   # plugin stdout/stderr capture
                                        # (the agent itself logs to journal)

The installer also:

• Creates the ongrid-edge system user (no home, no shell).
• Adds ongrid-edge to adm and systemd-journal so the logs plugin (promtail) can read /var/log/* (root:adm 640) and the journal.
• systemctl daemon-reload && systemctl enable --now ongrid-edge.

Verify

The installer waits up to 20 seconds (override with ONGRID_INSTALL_WAIT=N) for the agent to log agent: registered with cloud to the journal. A healthy install prints:

[INFO]  waiting for tunnel handshake (up to 20s)...

--- self-check ---
[OK]    plugin binary present: promtail
[OK]    plugin binary present: otelcol-contrib
[OK]    plugin binary present: node_exporter
[OK]    plugin binary present: process_exporter
[OK]    journald readable by ongrid-edge
[OK]    data-plane host 203.0.113.10:443 reachable (TCP)
[OK]    self-check passed

[OK]    installed:    ongrid-edge v0.7.159
[OK]    connected:    edge_id=42 via 203.0.113.10:40012
[OK]    tail logs:    journalctl -u ongrid-edge -f

If STATUS=failed or pending, the installer dumps the last 20 journal lines and prompts you toward the most likely fix. Manual checks:

# Service state
sudo systemctl status ongrid-edge

# Live journal
sudo journalctl -u ongrid-edge -f

# Test the data plane reachability
curl -kI https://203.0.113.10/

# Test the control plane reachability
nc -vz 203.0.113.10 40012

The most common failures, and what they mean:

Symptom	Likely cause	Fix
unauthorized in journal	access/secret key typo or stale key	Rotate edge in UI; re-run installer with new keys.
connection refused on :40012	frontier broker not exposed / firewall	Check iptables / cloud SG; verify docker compose ps frontier on manager.
Self-check: plugin binary MISSING	Old install before plugin bundle, or curl from a manager that never ran install.sh	Re-run the install command — it always re-fetches plugin binaries.
Self-check: cannot read journal	ongrid-edge not in systemd-journal group	sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge.
Edge "online" but Logs/Traces empty	ONGRID_PUBLIC_URL on manager points at internal IP	Edit /opt/ongrid/.env on manager; restart compose.

See it in the UI

• Edges — green dot next to your edge name. Card shows hostname, kernel, distro, total RAM, disk, agent version.
• Monitor — CPU / memory / disk / load panels populate within ~30s.
• Logs — pick the edge, see /var/log/* and journald tail.
• Topology — host node appears.

Re-register / rotate keys

If you need to rotate the secret key (compromise, lost key, manager re-install):

1. In the UI, Edges → <your edge> → Rotate keys. This invalidates the old secret and shows a new one.
2. Copy the new install command. It's the same one-liner with the new --access-key / --secret-key.
3. On the edge host, re-run the install command. It will:
   • Stop the running ongrid-edge cleanly before overwriting the binary,
   • Refetch the binary (so an old edge picks up the manager's version),
   • Refetch the plugin binaries,
   • Rewrite /etc/ongrid-edge/ongrid-edge.env with the new keys (mode 0640, owner root:ongrid-edge),
   • systemctl restart ongrid-edge,
   • Re-run the self-check.

The same flow is what you use to upgrade an edge to a new manager. Re-registration is idempotent.

Uninstall

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- --uninstall

Stops + disables the service, removes the binary, the systemd unit, and the env directory. Preserves /var/log/ongrid-edge so you can keep the plugin log files for forensics.

Behind a corporate proxy / firewall

The two outbound destinations are:

• <manager-host>:40012 — geminio tunnel, plain TCP (TLS-on-wire if the manager's frontier is configured for it; the OSS build is plain TCP behind nginx-fronted geminio).
• <manager-host>:443 — HTTPS for plugin data plane + binary download + upgrade bundle fetch.

If your egress goes through an http proxy, set HTTPS_PROXY in /etc/systemd/system/ongrid-edge.service.d/proxy.conf:

[Service]
Environment=HTTPS_PROXY=http://proxy.corp:3128
Environment=NO_PROXY=127.0.0.1,localhost

Then systemctl daemon-reload && systemctl restart ongrid-edge.

What's next

• First-boot checklist — once a couple of edges are checking in, the operator-side setup (alerts, channels, knowledge base).
• Upgrade — how ongrid-edge updates itself on operator command (one-button-upgrade from the UI).
• Platforms / Linux edge — distro matrix, distros known to work, SELinux/AppArmor notes.