CLI

Ongrid liefert zwei Binaries aus:

• ongrid — der Cloud-Manager. Läuft innerhalb des Manager-Containers.
• ongrid-edge — der Edge-Agent. Läuft als systemd-Service auf Linux-Hosts.

Beide sind dafür ausgelegt, über Umgebungsvariablen konfiguriert zu werden (Umgebungsvariablen), nicht über Flags. Die CLI-Oberfläche ist absichtlich klein gehalten — gerade genug, um die Version und eine Hilfe-Übersicht zu drucken. Alles, was in Produktions-Deploys wie ein Flag aussieht, wurde wahrscheinlich als ONGRID_*-Env in /etc/ongrid-edge/ongrid-edge.env oder deploy/docker-compose.yml gesetzt.

ongrid (Manager)

Liest jede ONGRID_*-Env-Variable, die das Binary kennt, öffnet seine Listener und läuft bis SIGINT / SIGTERM. Es gibt keine erforderlichen Argumente und keine Subkommandos.

Flags

Der Manager bietet keine dokumentierten Flags. Die einzige argv-Behandlung ist die der Standard-Go-Laufzeit: jedes unbekannte Flag wird ignoriert. Künftige Ops-Tooling-Flags (Migrationen erzwingen, Config dumpen, Bootstrap-Admin regenerieren) werden unter dem ops-Label auf GitHub verfolgt.

Prozessmodell

ongrid
  ├─ HTTP listener on $ONGRID_HTTP_ADDR (:8080)
  ├─ /metrics listener on $ONGRID_METRICS_ADDR (:9100)
  ├─ geminio service-end SDK dial to $ONGRID_FRONTIER_ADDR (frontier:40011)
  ├─ alert evaluator goroutine (interval $ONGRID_ALERT_EVAL_INTERVAL)
  ├─ DB pool sampler (10s tick)
  └─ background investigators (one goroutine per investigation request)

Health

curl http://localhost:8080/healthz   # always 200 once the server is up
curl http://localhost:8080/readyz    # 200 when DB + frontier dial are healthy

Stoppen / Neustarten

docker compose -f deploy/docker-compose.yml restart ongrid
docker compose -f deploy/docker-compose.yml down
docker compose -f deploy/docker-compose.yml up -d

Graceful Shutdown: der Manager verdrahtet SIGINT / SIGTERM mit dem Wurzelkontext seiner errgroup. Alle Goroutines stoppen bei Context-Cancel; In-Flight-HTTP-Requests erhalten bis zu 10 Sekunden zum Abschluss.

ongrid-edge (Agent)

Das Edge-Binary unterstützt zwei Flags vor jedem env-gesteuerten Startup. Sie werden ganz oben in main() behandelt, sodass sie auch auf einem fehlkonfigurierten Host ausgegeben werden und exiten.

Flag	Alias	Verhalten
--version	-v	Druckt ongrid-edge <version> und beendet mit 0.
--help	-h	Druckt ongrid-edge <version> plus einen einzeiligen Hinweis auf die systemd-Konfiguration, dann beendet mit 0.

Wortgetreu aus cmd/ongrid-edge/main.go:

$ ongrid-edge --version
ongrid-edge v0.7.167

$ ongrid-edge --help
ongrid-edge v0.7.167
Run as a systemd service. See /etc/ongrid-edge/ongrid-edge.env for config.

Es gibt kein --config /path-Flag. Jede Einstellung kommt aus der Umgebung. Die systemd-Unit lädt /etc/ongrid-edge/ongrid-edge.env via EnvironmentFile=; für Ad-hoc-Läufe (Dev auf macOS, Debugging) setzen Sie sie in Ihrer Shell.

Erforderliche Env zum Starten

Der Agent bootet unabhängig davon, kann aber erst dann nützliche Arbeit leisten, wenn diese drei gesetzt sind:

export ONGRID_EDGE_CLOUD_ADDR=ongrid.example.com:40012
export ONGRID_EDGE_ACCESS_KEY=<from manager UI>
export ONGRID_EDGE_SECRET_KEY=<from manager UI>

Prozessmodell

ongrid-edge
  ├─ tunnel dial to $ONGRID_EDGE_CLOUD_ADDR
  ├─ /metrics + /healthz listener on :9101 (localhost)
  ├─ embedded collector (gopsutil)
  ├─ plugin supervisor (subprocess promtail / otelcol-contrib / node_exporter / process-exporter)
  ├─ skill dispatcher (handles execute_skill RPCs from manager)
  └─ webshell port-forwarder (handles open_shell RPCs from manager)

Der Agent forkt nicht. Plugins sind erstklassige Kindprozesse, die vom prozessinternen Supervisor verwaltet werden; wenn ein Plugin abstürzt, startet der Supervisor es mit exponentiellem Backoff neu und meldet den Fehler beim nächsten Heartbeat (sichtbar auf der Edges-Seite als health.last_error).

Stoppen / Neustarten

sudo systemctl restart ongrid-edge
sudo systemctl stop ongrid-edge
sudo systemctl status ongrid-edge
journalctl -u ongrid-edge -f

Deinstallieren

# from a running edge:
curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

Entfernt das Binary, die Env-Datei, die systemd-Unit, die Plugin-Binaries unter /usr/local/lib/ongrid-edge/, behält aber /var/log/ongrid-edge/.

Debug-Flags via Env

Diese haben keine CLI-Flags, sind aber nützlich genug, um sie zu kennen:

Variable	Wirkung
ONGRID_LOG_LEVEL=debug	schaltet slog auf debug; verdoppelt das Heartbeat-Log-Volumen
ONGRID_EDGE_PLUGIN_BIN_DIR=...	überschreibt das Plugin-Binary-Verzeichnis (Standard /usr/local/lib/ongrid-edge)
ONGRID_EDGE_PLUGIN_WORK_DIR=...	überschreibt die Plugin-Runtime-Dirs (Standard /var/lib/ongrid-edge/plugins)
ONGRID_EDGE_UPGRADE_STAGE_DIR=""	deaktiviert das ADR-024 Whole-Bundle-Staging (leer setzen)
NO_COLOR=1	streift ANSI-Codes aus der install.sh-Ausgabe (vom Installer verwendet, nicht vom Agent)

install.sh (der curl-pipe-Installer)

Technisch gesehen kein Binary, aber er hat eine CLI, die dokumentenswert ist. Nutzung:

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- \
    --access-key=KEY \
    --secret-key=SECRET \
    --server-edge-addr=<host>:40012 \
    --server-http-addr=<host>:443

Flags

Flag	Pflicht	Beschreibung
--access-key=KEY	ja (Install)	per-edge Access-Key (aus der Manager-UI)
--secret-key=SECRET	ja (Install)	passendes Secret
--server-edge-addr=HOST:PORT	ja (Install)	Tunnel-Endpunkt (Frontier-Broker)
--server-http-addr=HOST[:PORT]	ja (Install)	nginx-Vordertür; verwendet für Binary-Downloads und Self-Check
--uninstall	nein	Agent stoppen und entfernen (behält /var/log/ongrid-edge/)
-h, --help	nein	Nutzung drucken

Env, die er liest

Variable	Standard	Wirkung
ONGRID_INSTALL_WAIT	20	Sekunden warten, bis der Agent „registered with cloud" loggt, bevor Erfolg gemeldet wird
NO_COLOR	unset	deaktiviert ANSI-Farben

Exit-Codes

• 0 — installiert und registriert (oder deinstalliert).
• 1 — Installation abgeschlossen, aber Registrierung erfolgte nicht (Netzwerk, falsche Keys); verwenden Sie journalctl -u ongrid-edge -f zur Diagnose.
• 2 — fehlerhafter Aufruf (fehlendes Pflicht-Flag).

Siehe auch

• Umgebungsvariablen — die eigentliche Konfigurationsoberfläche.
• Linux (edge) — Details zur systemd-Unit, was der Installer auf die Platte legt.
• REST API — die Oberfläche, die der Manager Clients bereitstellt.