Umgebungsvariablen
Sowohl ongrid als auch ongrid-edge werden ausschließlich über Umgebungsvariablen konfiguriert. Kein YAML. Die kanonische Verdrahtung liegt in internal/pkg/config/config.go und im Compose-Env-Block unter deploy/docker-compose.yml. Jede Variable unten wird beim Start gelesen; der Manager macht kein Hot-Reload.
Tabellen gruppieren Variablen nach Subsystem. Gezeigte Defaults sind das, was das Binary nimmt, wenn die Variable nicht gesetzt oder leer ist. „Pflicht" bedeutet „das Feature in Spalte 1 funktioniert nicht ohne sie".
HTTP- & Metrik-Listener
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_HTTP_ADDR | string | :8080 | TCP-Listen für die API + SPA. nginx im Compose-Stack proxyt /api/* hierhin. |
ONGRID_METRICS_ADDR | string | :9100 | TCP-Listen für /metrics. Wird von Prometheus gescraped. |
ONGRID_TUNNEL_ADDR | string | :40012 | Geminio-Broker-Listen. Wird vom frontier-Service gebunden, nicht vom Manager selbst. |
ONGRID_PUBLIC_URL | string | leer | Kanonische https://...-URL, die der Manager Edges als Daten-Ebenen-Endpunkt aushändigt (Log-/Trace-Ingest, Edge-Bundle-Download). Leer deaktiviert die Daten-Ebenen-Plugin-Endpunkte. In Produktion setzen. |
Datenbank (MySQL Standard, SQLite opt-in)
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_DB_DIALECT | string | mysql | mysql (Standard) oder sqlite. Leer wird als mysql behandelt. |
ONGRID_DB_DSN | string | ongrid:ongrid@tcp(127.0.0.1:3306)/ongrid?parseTime=true&charset=utf8mb4&loc=Local | MySQL-DSN. In Produktion erforderlich. |
ONGRID_DB_PATH | string | ./data/ongrid.db | SQLite-Datenbank-Dateipfad. :memory: wird in Tests akzeptiert. |
JWT (iam)
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_JWT_SECRET | string | dev-insecure-secret-change-me | HS256-Signaturschlüssel für Access- + Refresh-Tokens. Pflicht; der Default verweigert die Token-Ausgabe in Produktions-Builds. |
ONGRID_JWT_ACCESS_TTL | duration | 15m | Access-Token-TTL. |
ONGRID_JWT_REFRESH_TTL | duration | 168h (7d) | Refresh-Token-TTL. |
Dauern akzeptieren Go-time.ParseDuration-Syntax (15m, 2h, 30s). Eine bloße Ganzzahl wird als Sekunden interpretiert.
LLM-Provider
Der Chat-Agent unterstützt sechs erstklassige Provider plus einen Custom-Slot (OpenAI-kompatibel). Jeder Provider wird durch seinen API-Key gesteuert — leerer Key = Provider erscheint nicht im Chat-Picker.
OpenAI
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_OPENAI_API_KEY | string | leer | OpenAI-API-Key. Leer = OpenAI im Picker ausgeblendet. |
ONGRID_OPENAI_MODEL | string | gpt-5.4 | Default-Modell, wenn OpenAI der ausgewählte Provider ist. |
ONGRID_OPENAI_BASE_URL | string | leer | Base-URL überschreiben für OpenAI-kompatible Relays (Azure / vLLM / Ollama / one-api). |
Anthropic, Zhipu, Gemini, DeepSeek, Kimi
Jeder Provider hat dieselben drei Keys (API-Key / Default-Modell / Base-URL) und einen vierten (MODELS, komma-getrennte Liste auswählbarer Modell-Slugs):
| Variable | Standard |
|---|---|
ONGRID_ANTHROPIC_API_KEY | leer |
ONGRID_ANTHROPIC_MODEL | claude-sonnet-4-6 |
ONGRID_ANTHROPIC_BASE_URL | leer |
ONGRID_ANTHROPIC_MODELS | claude-opus-4-7,claude-sonnet-4-6,claude-haiku-4-5 |
ONGRID_ZHIPU_API_KEY | leer |
ONGRID_ZHIPU_MODEL | glm-4.7 |
ONGRID_ZHIPU_BASE_URL | leer |
ONGRID_ZHIPU_MODELS | glm-5.1,glm-5,glm-4.7,glm-4.7-flash |
ONGRID_GEMINI_API_KEY | leer |
ONGRID_GEMINI_MODEL | gemini-2.5-pro |
ONGRID_GEMINI_BASE_URL | leer |
ONGRID_GEMINI_MODELS | gemini-3.5-flash,gemini-2.5-pro,gemini-2.5-flash |
ONGRID_DEEPSEEK_API_KEY | leer |
ONGRID_DEEPSEEK_MODEL | deepseek-v4-flash |
ONGRID_DEEPSEEK_BASE_URL | leer |
ONGRID_DEEPSEEK_MODELS | deepseek-v4-pro,deepseek-v4-flash,deepseek-reasoner |
ONGRID_KIMI_API_KEY | leer |
ONGRID_KIMI_MODEL | kimi-k2.6 |
ONGRID_KIMI_BASE_URL | leer |
ONGRID_KIMI_MODELS | kimi-k2.6,kimi-k2.5,moonshot-v1-128k |
Routing & Budget
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_LLM_DEFAULT_PROVIDER | string | leer | Provider, der verwendet wird, wenn eine Anfrage keinen angibt. Leer = erster konfigurierter Provider (alphabetisch). Setzen Sie dies, wenn ein bestimmter Provider die Site-Voreinstellung sein soll. |
ONGRID_LLM_DAILY_TOKEN_LIMIT | int | 0 | Globale per-UTC-Tag-Token-Obergrenze. 0 = unbegrenzt. |
Agent-Kernel & Werkzeuge
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_AGENT_KERNEL | string | graph | graph aktiviert den eino-Graph-Kernel + SkillRegistry.Resolve-Aktivierungs-Keyword-Filter + ToolBag-Deferral-Pipeline. legacy ist der ältere For-Loop-Runner mit allen Werkzeugen stets im vollständigen Schema. Nur zum Bisect auf legacy umstellen. |
ONGRID_TOOLBAG_DEFERRAL_THRESHOLD | int | 30 | Tool-Anzahl-Schwelle, oberhalb derer Specialty-Tier-Tools redigierte Schemata erhalten (LLM muss ToolSearch aufrufen, um zu expandieren). |
ONGRID_SKILLS_EXTERNAL_DIRS | csv | leer | Komma-/Doppelpunkt-getrennte absolute Pfade, die der Skill-Loader nach skill.json-Manifesten durchsucht. Jeder muss absolut sein; relative oder fehlende Einträge werden mit einer Log-Zeile übersprungen. |
Frontier-Broker-Client
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_FRONTIER_ADDR | string | frontier:40011 | Service-gebundener Listen des Upstream-Frontier-Brokers, den der Manager wählt. |
ONGRID_FRONTIER_SERVICE_NAME | string | ongrid-manager | Beim Connect gemeldeter Bezeichner. |
ONGRID_FRONTIER_DISABLED | bool | false | Den langlebigen Service-End-Dial komplett überspringen. Vom e2e-Harness verwendet — Features, die den Broker brauchen (webssh, Edge-Reverse-Aufrufe), fehlen am Call-Site. |
Cloud-seitiges Prometheus
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_PROM_ENABLED | bool | false | Steuert die Prometheus-Verdrahtung. Wenn false, läuft der Manager ohne Metrikspeicher; push_prom_samples verwirft still, und query_promql wird nicht als Werkzeug registriert. |
ONGRID_PROM_URL | string | http://prometheus:9090 | Prom-Server-Root-URL. |
ONGRID_PROM_REMOTE_WRITE_URL | string | leer | Genauer remote_write-Endpunkt, wenn das Upstream nicht unter /api/v1/write gewurzelt ist (Mimir / Cortex / VictoriaMetrics-Gateway). |
ONGRID_PROM_QUERY_URL | string | leer | Query-API-Wurzel für query_promql. Leer fällt auf ONGRID_PROM_URL zurück. |
ONGRID_PROM_TLS_INSECURE | bool | false | TLS-Cert-Verifikation überspringen. |
ONGRID_PROM_TLS_CA_FILE | string | leer | PEM-Datei mit der Root-CA, die zur Verifikation des TSDB-Certs verwendet wird. Leer = System-Roots. |
Grafana
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_GRAFANA_INTERNAL_URL | string | http://grafana:3000/grafana | URL, die der Manager verwendet, um Grafana über das Docker-Netzwerk zu erreichen. |
ONGRID_GRAFANA_BOOTSTRAP_USER | string | admin | Einmaliger Admin-Benutzer, der zum Auto-Erstellen des ongrid Service Accounts + Tokens verwendet wird. |
ONGRID_GRAFANA_BOOTSTRAP_PASSWORD | string | leer | Bootstrap-Passwort; leer deaktiviert Bootstrap (manuell erstelltes SA-Token in der UI einfügen). |
ONGRID_GRAFANA_TLS_INSECURE | bool | false | Cert-Verifikation für den Bootstrap-Aufruf überspringen. |
ONGRID_GRAFANA_ROOT_URL | string | %(protocol)s://%(domain)s/grafana/ | An GF_SERVER_ROOT_URL weitergeleitet. |
Logs & Traces (Datenebene)
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_LOG_QUERY_URL | string | http://loki:3100 | Loki-API-Wurzel, mit der der Manager für query_range / Labels / Werte spricht. Leer = Logs-Seite gibt 503 zurück. |
ONGRID_TRACE_QUERY_URL | string | http://tempo:3200 | Tempo-HTTP-Listener-Wurzel für /api/search, /api/traces/<id>, /api/search/tag/<tag>/values. Leer = Traces-Seite gibt 503 zurück. |
Die Edge-Daten-Ebenen-Endpunkte (wo die Logs-/Traces-Plugins POSTen) werden aus ONGRID_PUBLIC_URL abgeleitet; siehe Telemetrie-Datenebene.
Eingebaute Alarmschwellen
Diese treiben die vier kanonischen eingebauten Regeln über die geschlossene Host-Metrik-Menge an. Auf 0 setzen, um zu deaktivieren.
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_ALERT_ENABLED | bool | true | Hauptschalter für die eingebaute Host-Alarmauswertung. |
ONGRID_ALERT_COOLDOWN | duration | 10m | Per-(Edge, Regel) Cooldown. Benachrichtigungen innerhalb dieses Fensters werden unterdrückt. |
ONGRID_ALERT_CPU_PERCENT | float | 90 | Feuert, wenn cpu_pct >= threshold. |
ONGRID_ALERT_MEM_PERCENT | float | 90 | Feuert, wenn mem_pct >= threshold. |
ONGRID_ALERT_DISK_USED_PERCENT | float | 90 | Feuert, wenn disk_used_pct >= threshold. |
ONGRID_ALERT_LOAD1 | float | 0 | Feuert, wenn load1 >= threshold. 0 deaktiviert (Load variiert zu stark über Host-Shapes für einen nützlichen Default). |
ONGRID_ALERT_EVAL_INTERVAL | duration | 5m | Wie oft der Pipeline-Evaluator Edges scannt und Prom abfragt. |
ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD | duration | 90s | Heartbeat-Staleness, oberhalb derer eine Edge als offline zählt. |
ONGRID_ALERT_PROM_INGEST_FAIL_LIMIT | int | 5 | Aufeinanderfolgende remote_write-Fehlerzahl, bei der prom_ingest_fail feuert. |
Benachrichtigungen
Hauptschalter + die vier eingebauten Kanaltypen. UI-erstellte Kanäle tragen ihr eigenes enabled-Flag und werden davon nicht betroffen.
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_NOTIFY_ENABLED | bool | true | Hauptschalter für ausgehende Benachrichtigungen. |
ONGRID_NOTIFY_DEFAULT_CHANNELS | csv | leer | Geordnete Kanalnamen-Liste, die verwendet wird, wenn ein Aufrufer keine Ziele angibt. |
ONGRID_NOTIFY_TIMEOUT | duration | 10s | Per-Kanal-Sende-Timeout. |
ONGRID_NOTIFY_WEBHOOK_ENABLED | bool | false | Den env-konfigurierten Webhook-Kanal aktivieren. |
ONGRID_NOTIFY_WEBHOOK_NAME | string | webhook | Anzeigename. |
ONGRID_NOTIFY_WEBHOOK_URL | string | leer | POST-Endpunkt. |
ONGRID_NOTIFY_WEBHOOK_SECRET | string | leer | Optionales HMAC-Secret. |
ONGRID_NOTIFY_SLACK_ENABLED | bool | false | Den env-konfigurierten Slack-Kanal aktivieren. |
ONGRID_NOTIFY_SLACK_NAME | string | slack | Anzeigename. |
ONGRID_NOTIFY_SLACK_WEBHOOK_URL | string | leer | Incoming-Webhook-URL. |
ONGRID_NOTIFY_FEISHU_ENABLED | bool | false | Den env-konfigurierten Larksuite-/Feishu-Kanal aktivieren. |
ONGRID_NOTIFY_FEISHU_NAME | string | feishu | Anzeigename. |
ONGRID_NOTIFY_FEISHU_WEBHOOK_URL | string | leer | Custom-Bot-URL. |
ONGRID_NOTIFY_FEISHU_SECRET | string | leer | Signing-Secret. |
ONGRID_NOTIFY_DINGTALK_ENABLED | bool | false | Den env-konfigurierten DingTalk-Kanal aktivieren. |
ONGRID_NOTIFY_DINGTALK_NAME | string | dingtalk | Anzeigename. |
ONGRID_NOTIFY_DINGTALK_WEBHOOK_URL | string | leer | Custom-Bot-URL. |
ONGRID_NOTIFY_DINGTALK_SECRET | string | leer | Signing-Secret. |
Für WeCom- und Telegram-Kanäle erstellen Sie diese über die Settings → Channels UI — sie sind erstklassig, haben aber keine Env-Konfigurations-Abkürzung.
Bootstrap-Admin
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_ADMIN_EMAIL | string | leer | E-Mail des Bootstrap-Admins. Wenn leer, wird kein Admin geseedet; Sie müssen sich beim ersten Boot über die UI registrieren. |
ONGRID_ADMIN_PASSWORD | string | leer | Initiales Passwort. Der Operator wird erwartet, es beim ersten Login zu ändern. |
Edge-Agent
Diese werden von ongrid-edge konsumiert und vom Installer in /etc/ongrid-edge/ongrid-edge.env geschrieben.
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_EDGE_CLOUD_ADDR | string | 127.0.0.1:40012 | Frontier-Broker host:port. Der Agent wählt dies mit TLS. |
ONGRID_EDGE_ACCESS_KEY | string | leer | Per-Edge-Access-Key. Vom Manager ausgegeben, wenn Sie eine Edge in der UI erstellen. |
ONGRID_EDGE_SECRET_KEY | string | leer | Passendes Secret. Wird einmal bei Edge-Erstellung gezeigt; rotieren Sie über die UI. |
ONGRID_EDGE_COLLECTOR_MODE | string | off | off (Standard; die hostmetrics- + procmetrics-Plugins handhaben Metriken), auto (Legacy embedded + Scraper), embedded (nur embedded Push), scrape (Multi-Target-HTTP-Scraper). |
ONGRID_EDGE_SCRAPE_CONFIG_FILE | string | /etc/ongrid-edge/scrape.yaml | Pfad zur Scrape-Config-YAML. Nur konsultiert, wenn COLLECTOR_MODE=scrape. |
ONGRID_EDGE_COLLECTOR_INTERVAL | duration | 10s | Wie oft der embedded Collector snapshotet. Scrape-Modus ignoriert dies. |
ONGRID_EDGE_PLUGIN_BIN_DIR | string | /usr/local/lib/ongrid-edge | Verzeichnis mit Plugin-Binaries (promtail, otelcol-contrib, node_exporter, process_exporter). |
ONGRID_EDGE_PLUGIN_WORK_DIR | string | /var/lib/ongrid-edge/plugins | Per-Plugin-Runtime-Dirs (Configs, PID-Dateien, Queue-Spool). |
ONGRID_EDGE_UPGRADE_STAGE_DIR | string | /var/lib/ongrid-edge/.upgrade | ADR-024 Staged-Bundle-Verzeichnis. Leer deaktiviert Remote-Whole-Bundle-Upgrades. |
ONGRID_INSTALL_WAIT | int | 20 | Sekunden, die der curl-pipe-Installer das Journal pollt und auf „registered with cloud" wartet. |
Embedding & RAG
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_EMBEDDING_PROVIDER | string | zhipu | zhipu (Standard; ruft GLM-Embedding-API auf), local (verwendet ein On-Disk-bge-Modell), openai (verwendet OpenAI-Embeddings). |
ONGRID_EMBEDDING_LOCAL_MODEL_PATH | string | leer | Absoluter Pfad zum lokalen Modell, wenn PROVIDER=local. Das Release-Tarball staget bge-base-en-v1.5 unter .cache/. |
ONGRID_VAULT_REPO_URL | string | https://github.com/ongridio/vault | Upstream-Vault-Repository, aus dem der Manager Basiswissen zieht. Für Air-Gapped-Mirrors überschreiben. |
Locale & sonstiges
| Variable | Typ | Standard | Beschreibung |
|---|---|---|---|
ONGRID_DEFAULT_LOCALE | string | en | Default-Locale für automatische LLM-Ausgaben (Alarm-Investigations, geplante Zusammenfassungen). UI-getriggerter Chat verwendet stattdessen die UI-Locale des Benutzers. |
Siehe auch
- REST API — Endpunkte, die diese Env-Variablen verdrahten.
- CLI — die Command-Line-Flags der beiden Binaries.
- Telemetrie-Datenebene — warum sich Log-/Trace-Endpunkte vom Tunnel unterscheiden.
- Architektur — wo jede Env-Variable im Stack-Diagramm lebt.