Linux (edge)

The edge agent (ongrid-edge) runs on every host you want Ongrid to observe. On Linux, it installs as a systemd service via a single curl-pipe command. The agent is a single static Go binary plus four plugin binaries (promtail, node_exporter, process-exporter, otelcol-contrib).

Architectures

GOOS	GOARCH	Status
linux	amd64	first-class
linux	arm64	first-class

The installer reads uname -m and picks the matching binary, downloaded from the manager's /edge/ static path:

x86_64 / amd64  → amd64
aarch64 / arm64 → arm64
anything else   → error: "unsupported arch"

Supported distributions

We test against the same set as the server. In practice anything with systemd 245+ (so StateDirectory= works) and glibc 2.31+ runs the agent fine.

Distribution	Tested on
Ubuntu	20.04 LTS, 22.04 LTS, 24.04 LTS
Debian	11 (bullseye), 12 (bookworm)
RHEL	8, 9
Rocky Linux	8, 9
AlmaLinux	8, 9
Amazon Linux	2023

If your distribution still uses sysvinit, OpenRC, or runit, see the "non-systemd" section below.

What the installer drops

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 lays down the following on disk:

Path	Purpose
/usr/local/bin/ongrid-edge	the agent binary
/usr/local/lib/ongrid-edge/promtail	logs plugin
/usr/local/lib/ongrid-edge/otelcol-contrib	traces plugin
/usr/local/lib/ongrid-edge/node_exporter	host-metrics plugin
/usr/local/lib/ongrid-edge/process_exporter	proc-metrics plugin
/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh	ADR-024 staged-bundle swap hook
/etc/ongrid-edge/ongrid-edge.env	access/secret key, cloud addr (mode 640, root:ongrid-edge)
/etc/systemd/system/ongrid-edge.service	the systemd unit
/var/lib/ongrid-edge/	StateDirectory: pending-upgrade staging, dedupe state
/var/log/ongrid-edge/	local log directory (mode 750, owned by ongrid-edge)

A system user ongrid-edge is created (no shell, no home) and added to two groups: adm (so promtail can read /var/log/* whose mode is 640 root:adm) and systemd-journal (so it can read the journal).

The systemd unit

Verbatim from deploy/install/edge/install.sh:

[Unit]
Description=ongrid edge agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/ongrid-edge/ongrid-edge.env
ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge
Restart=always
RestartSec=5
User=ongrid-edge
Group=ongrid-edge
AmbientCapabilities=CAP_NET_ADMIN
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
StateDirectory=ongrid-edge
StateDirectoryMode=0755
ReadWritePaths=/var/log/ongrid-edge
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Highlights worth knowing:

• ProtectSystem=strict makes /usr, /boot, and /etc read-only. The agent never writes outside StateDirectory= (/var/lib/ongrid-edge) or ReadWritePaths= (/var/log/ongrid-edge).
• AmbientCapabilities=CAP_NET_ADMIN is what lets a few edge skills do read-only network introspection (ss -ntlp-style probes via nft list ruleset, conntrack reads). The agent itself never opens raw sockets.
• ExecStartPre=-+ (the - ignores failure, + runs as root) wires in the ADR-024 staged-bundle swap. If a pending upgrade was staged on the previous boot, this hook applies it, then exits 0 either way.
• StandardOutput=journal is the contract with promtail — the agent's own logs are journald-readable, not on stdout-of-pid-1, and promtail's journal source picks them up.

Log source: journald, not syslog

Promtail is configured to scrape journald (/run/log/journal for non-persistent, /var/log/journal for persistent). It does not tail /var/log/syslog or /var/log/messages. If your distribution ships rsyslog and you have disabled the persistent journal, enable it:

mkdir -p /var/log/journal
systemd-tmpfiles --create --prefix /var/log/journal
systemctl restart systemd-journald

Without a persistent journal the logs plugin still works but its history is bounded by RAM (the runtime journal at /run/log/journal).

Non-systemd Linux (sysvinit / OpenRC / runit)

The curl-pipe installer hard-fails on a missing systemctl. You can still run the agent — drop the binary in /usr/local/bin/ongrid-edge, write your own init script that exports the three required envs (ONGRID_EDGE_CLOUD_ADDR, ONGRID_EDGE_ACCESS_KEY, ONGRID_EDGE_SECRET_KEY) and execs the binary, and you are done. You lose:

• Auto-restart on crash (replace with whatever your init system offers).
• The apply-pending-upgrade.sh hook, so remote whole-bundle upgrades (ADR-024) silently no-op.
• Plugin binaries (the installer also fetches those, see above).

Those four plugin binaries are also reachable at https://<manager>/edge/<name>-linux-<arch>; download them by hand into a directory of your choice and point ONGRID_EDGE_PLUGIN_BIN_DIR at it.

Capabilities the agent does NOT need

• It does not need root at runtime (it runs as the ongrid-edge user).
• It does not need CAP_SYS_ADMIN, CAP_NET_RAW, or CAP_SYS_PTRACE. If a skill asks for any of those, the cmdpolicy gate refuses.
• It does not need Docker. The plugin runtime is a plain subprocess supervisor, not containers.

Ports the agent opens

Port	Bind	Why
9101	localhost	the agent's own /metrics and /healthz
9102	localhost	node_exporter (when the hostmetrics plugin is enabled)
9256	localhost	process-exporter (when the procmetrics plugin is enabled)

Only the outbound tunnel connection to the manager's port 40012 needs to traverse your firewall. No inbound ports need to be opened on the edge host.

Uninstalling

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

This stops the service, removes the binary, the env file, and the systemd unit. It deliberately leaves /var/log/ongrid-edge/ in place — purge it by hand if you want it gone.