Variables de entorno

Tanto ongrid como ongrid-edge se configuran exclusivamente a través de variables de entorno. Sin YAML. El cableado canónico vive en internal/pkg/config/config.go y en el bloque env de compose en deploy/docker-compose.yml. Cada variable de abajo se lee al arranque; el manager no hot-reloadea.

Las tablas agrupan variables por subsistema. Los defaults mostrados son lo que el binario elige cuando la variable no está seteada o está vacía. "Requerida" significa "la feature en la columna 1 no funcionará sin ella".

---

Listeners HTTP & métricas

Variable	Tipo	Default	Descripción
ONGRID_HTTP_ADDR	string	:8080	TCP listen para la API + SPA. nginx en el stack compose proxiya /api/* aquí.
ONGRID_METRICS_ADDR	string	:9100	TCP listen para /metrics. Scrapeado por Prometheus.
ONGRID_TUNNEL_ADDR	string	:40012	Listen del broker geminio. Bindeado por el servicio frontier, no por el propio manager.
ONGRID_PUBLIC_URL	string	empty	URL canónica https://... que el manager entrega a los edges como endpoint del data-plane (ingest de logs/trazas, descarga de bundle de edge). Vacío deshabilita los endpoints de plugin del data plane. Configura esto en producción.

---

Database (MySQL default, SQLite opt-in)

Variable	Tipo	Default	Descripción
ONGRID_DB_DIALECT	string	mysql	mysql (default) o sqlite. Vacío se trata como mysql.
ONGRID_DB_DSN	string	ongrid:ongrid@tcp(127.0.0.1:3306)/ongrid?parseTime=true&charset=utf8mb4&loc=Local	DSN de MySQL. Requerido en producción.
ONGRID_DB_PATH	string	./data/ongrid.db	Ruta del archivo de base de datos SQLite. :memory: es aceptado en tests.

---

JWT (iam)

Variable	Tipo	Default	Descripción
ONGRID_JWT_SECRET	string	dev-insecure-secret-change-me	Signing key HS256 para tokens access + refresh. Requerida; el default rehúsa emitir tokens en builds de producción.
ONGRID_JWT_ACCESS_TTL	duration	15m	TTL de access-token.
ONGRID_JWT_REFRESH_TTL	duration	168h (7d)	TTL de refresh-token.

Las durations aceptan la sintaxis Go time.ParseDuration (15m, 2h, 30s). Un entero desnudo se interpreta como segundos.

---

Providers LLM

El agente de chat soporta seis providers first-class más un slot Custom (compatible con OpenAI). Cada provider está gateado por su API key — key vacía = provider no expuesto al picker de chat.

OpenAI

Variable	Tipo	Default	Descripción
ONGRID_OPENAI_API_KEY	string	empty	API key de OpenAI. Vacía = OpenAI escondido del picker.
ONGRID_OPENAI_MODEL	string	gpt-5.4	Modelo default cuando OpenAI es el provider seleccionado.
ONGRID_OPENAI_BASE_URL	string	empty	Override de base URL para relays compatibles con OpenAI (Azure / vLLM / Ollama / one-api).

Anthropic, Zhipu, Gemini, DeepSeek, Kimi

Cada provider tiene las mismas tres keys (API key / modelo default / base URL) y una cuarta (MODELS, lista separada por comas de slugs de modelo seleccionables):

Variable	Default
ONGRID_ANTHROPIC_API_KEY	empty
ONGRID_ANTHROPIC_MODEL	claude-sonnet-4-6
ONGRID_ANTHROPIC_BASE_URL	empty
ONGRID_ANTHROPIC_MODELS	claude-opus-4-7,claude-sonnet-4-6,claude-haiku-4-5
ONGRID_ZHIPU_API_KEY	empty
ONGRID_ZHIPU_MODEL	glm-4.7
ONGRID_ZHIPU_BASE_URL	empty
ONGRID_ZHIPU_MODELS	glm-5.1,glm-5,glm-4.7,glm-4.7-flash
ONGRID_GEMINI_API_KEY	empty
ONGRID_GEMINI_MODEL	gemini-2.5-pro
ONGRID_GEMINI_BASE_URL	empty
ONGRID_GEMINI_MODELS	gemini-3.5-flash,gemini-2.5-pro,gemini-2.5-flash
ONGRID_DEEPSEEK_API_KEY	empty
ONGRID_DEEPSEEK_MODEL	deepseek-v4-flash
ONGRID_DEEPSEEK_BASE_URL	empty
ONGRID_DEEPSEEK_MODELS	deepseek-v4-pro,deepseek-v4-flash,deepseek-reasoner
ONGRID_KIMI_API_KEY	empty
ONGRID_KIMI_MODEL	kimi-k2.6
ONGRID_KIMI_BASE_URL	empty
ONGRID_KIMI_MODELS	kimi-k2.6,kimi-k2.5,moonshot-v1-128k

Routing & budget

Variable	Tipo	Default	Descripción
ONGRID_LLM_DEFAULT_PROVIDER	string	empty	Provider usado cuando un request no especifica uno. Vacío = primer provider configurado (alfabético). Configura esto cuando quieras un provider específico como default del sitio.
ONGRID_LLM_DAILY_TOKEN_LIMIT	int	0	Techo global de tokens por UTC-día. 0 = ilimitado.

---

Kernel del agente & tools

Variable	Tipo	Default	Descripción
ONGRID_AGENT_KERNEL	string	graph	graph habilita el kernel de grafo eino + filtro de activation-keyword de SkillRegistry.Resolve + pipeline de deferral de ToolBag. legacy es el runner viejo de for-loop con todas las tools siempre con schema completo. Cambia a legacy solo para bisect.
ONGRID_TOOLBAG_DEFERRAL_THRESHOLD	int	30	Threshold de conteo de tool por encima del cual las tools de specialty-tier obtienen schemas redactados (el LLM debe llamar a ToolSearch para expandir).
ONGRID_SKILLS_EXTERNAL_DIRS	csv	empty	Paths absolutos separados por coma/colon que el skill loader scanea por manifests skill.json. Cada uno debe ser absoluto; entradas relativas o faltantes se saltan con una línea de log.

---

Cliente del broker frontier

Variable	Tipo	Default	Descripción
ONGRID_FRONTIER_ADDR	string	frontier:40011	Listen service-bound del broker upstream frontier al que el manager marca.
ONGRID_FRONTIER_SERVICE_NAME	string	ongrid-manager	Identificador reportado al conectar.
ONGRID_FRONTIER_DISABLED	bool	false	Saltarse la marcación service-end de larga vida totalmente. Usado por el harness e2e — features que requieren el broker (webssh, edge reverse calls) erran en el call site.

---

Prometheus cloud-side

Variable	Tipo	Default	Descripción
ONGRID_PROM_ENABLED	bool	false	Gatea el cableado de Prometheus. Cuando false el manager corre sin storage de métricas; push_prom_samples descarta silenciosamente, y query_promql no se registra como tool.
ONGRID_PROM_URL	string	http://prometheus:9090	URL raíz del servidor Prom.
ONGRID_PROM_REMOTE_WRITE_URL	string	empty	Endpoint remote_write exacto cuando el upstream no está rooteado en /api/v1/write (gateway Mimir / Cortex / VictoriaMetrics).
ONGRID_PROM_QUERY_URL	string	empty	Raíz de la API de query para query_promql. Vacío cae a ONGRID_PROM_URL.
ONGRID_PROM_TLS_INSECURE	bool	false	Saltar verificación de cert TLS.
ONGRID_PROM_TLS_CA_FILE	string	empty	Archivo PEM con la CA raíz usada para verificar el cert del TSDB. Vacío = raíces del sistema.

---

Grafana

Variable	Tipo	Default	Descripción
ONGRID_GRAFANA_INTERNAL_URL	string	http://grafana:3000/grafana	URL que el manager usa para alcanzar Grafana sobre la red docker.
ONGRID_GRAFANA_BOOTSTRAP_USER	string	admin	Usuario admin one-time usado para auto-crear la Service Account de ongrid + token.
ONGRID_GRAFANA_BOOTSTRAP_PASSWORD	string	empty	Password bootstrap; vacío deshabilita bootstrap (pega un SA token creado manualmente en la UI).
ONGRID_GRAFANA_TLS_INSECURE	bool	false	Saltar verificación de cert para la llamada bootstrap.
ONGRID_GRAFANA_ROOT_URL	string	%(protocol)s://%(domain)s/grafana/	Reenviado a GF_SERVER_ROOT_URL.

---

Logs & trazas (data plane)

Variable	Tipo	Default	Descripción
ONGRID_LOG_QUERY_URL	string	http://loki:3100	Raíz de la API de Loki con la que el manager habla para query_range / labels / values. Vacío = página de Logs devuelve 503.
ONGRID_TRACE_QUERY_URL	string	http://tempo:3200	Raíz del listener HTTP de Tempo para /api/search, /api/traces/<id>, /api/search/tag/<tag>/values. Vacío = página de Trazas devuelve 503.

Los endpoints del data plane del edge (donde los plugins de logs / trazas hacen POST) se derivan de ONGRID_PUBLIC_URL; ver Data plane de telemetría.

---

Thresholds de alertas integradas

Estos manejan las cuatro reglas integradas canónicas sobre el conjunto cerrado de métricas de host. Setea a 0 para deshabilitar.

Variable	Tipo	Default	Descripción
ONGRID_ALERT_ENABLED	bool	true	Switch maestro para evaluación de alertas de host integradas.
ONGRID_ALERT_COOLDOWN	duration	10m	Cooldown per-(edge, regla). Notificaciones dentro de esta ventana se suprimen.
ONGRID_ALERT_CPU_PERCENT	float	90	Dispara cuando cpu_pct >= threshold.
ONGRID_ALERT_MEM_PERCENT	float	90	Dispara cuando mem_pct >= threshold.
ONGRID_ALERT_DISK_USED_PERCENT	float	90	Dispara cuando disk_used_pct >= threshold.
ONGRID_ALERT_LOAD1	float	0	Dispara cuando load1 >= threshold. 0 deshabilita (load varía demasiado a través de formas de host para un default útil).
ONGRID_ALERT_EVAL_INTERVAL	duration	5m	Con qué frecuencia el evaluator del pipeline scanea edges y consulta Prom.
ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD	duration	90s	Staleness de heartbeat por encima de la cual un edge cuenta como offline.
ONGRID_ALERT_PROM_INGEST_FAIL_LIMIT	int	5	Conteo consecutivo de fallos de remote_write al que prom_ingest_fail dispara.

---

Notificaciones

Switch maestro + los cuatro tipos de canal integrados. Los canales creados en UI llevan su propio flag enabled y no se ven afectados por estos.

Variable	Tipo	Default	Descripción
ONGRID_NOTIFY_ENABLED	bool	true	Switch maestro para notificaciones salientes.
ONGRID_NOTIFY_DEFAULT_CHANNELS	csv	empty	Lista ordenada de nombres de canal usada cuando un caller no especifica destinos.
ONGRID_NOTIFY_TIMEOUT	duration	10s	Timeout de send por-canal.
ONGRID_NOTIFY_WEBHOOK_ENABLED	bool	false	Habilita el canal webhook env-configurado.
ONGRID_NOTIFY_WEBHOOK_NAME	string	webhook	Nombre de display.
ONGRID_NOTIFY_WEBHOOK_URL	string	empty	Endpoint POST.
ONGRID_NOTIFY_WEBHOOK_SECRET	string	empty	Secret HMAC opcional.
ONGRID_NOTIFY_SLACK_ENABLED	bool	false	Habilita el canal Slack env-configurado.
ONGRID_NOTIFY_SLACK_NAME	string	slack	Nombre de display.
ONGRID_NOTIFY_SLACK_WEBHOOK_URL	string	empty	URL del Incoming Webhook.
ONGRID_NOTIFY_FEISHU_ENABLED	bool	false	Habilita el canal Larksuite / Feishu env-configurado.
ONGRID_NOTIFY_FEISHU_NAME	string	feishu	Nombre de display.
ONGRID_NOTIFY_FEISHU_WEBHOOK_URL	string	empty	URL Custom-Bot.
ONGRID_NOTIFY_FEISHU_SECRET	string	empty	Secret de firma.
ONGRID_NOTIFY_DINGTALK_ENABLED	bool	false	Habilita el canal DingTalk env-configurado.
ONGRID_NOTIFY_DINGTALK_NAME	string	dingtalk	Nombre de display.
ONGRID_NOTIFY_DINGTALK_WEBHOOK_URL	string	empty	URL Custom-Bot.
ONGRID_NOTIFY_DINGTALK_SECRET	string	empty	Secret de firma.

Para canales WeCom y Telegram, créalos vía la UI Settings → Channels — son first-class pero no tienen shortcut de env-configuration.

---

Admin bootstrap

Variable	Tipo	Default	Descripción
ONGRID_ADMIN_EMAIL	string	empty	Email del admin bootstrap. Si está vacío, no se siembra ningún admin; debes registrar desde la UI en el primer boot.
ONGRID_ADMIN_PASSWORD	string	empty	Contraseña inicial. Se espera que el operador la cambie en el primer login.

---

Agente edge

Estos los consume ongrid-edge, escritos en /etc/ongrid-edge/ongrid-edge.env por el installer.

Variable	Tipo	Default	Descripción
ONGRID_EDGE_CLOUD_ADDR	string	127.0.0.1:40012	host:port del broker frontier. El agente marca a esto con TLS.
ONGRID_EDGE_ACCESS_KEY	string	empty	Access key por-edge. Emitida por el manager cuando creas un edge en la UI.
ONGRID_EDGE_SECRET_KEY	string	empty	Secret matcheante. Mostrada una vez en la creación de edge; rota vía la UI.
ONGRID_EDGE_COLLECTOR_MODE	string	off	off (default; los plugins hostmetrics + procmetrics manejan métricas), auto (embedded + scraper legacy), embedded (solo embedded push), scrape (scraper HTTP multi-target).
ONGRID_EDGE_SCRAPE_CONFIG_FILE	string	/etc/ongrid-edge/scrape.yaml	Path al YAML de config de scrape. Solo consultado cuando COLLECTOR_MODE=scrape.
ONGRID_EDGE_COLLECTOR_INTERVAL	duration	10s	Con qué frecuencia el collector embedded snapshotea. El modo scrape ignora esto.
ONGRID_EDGE_PLUGIN_BIN_DIR	string	/usr/local/lib/ongrid-edge	Directorio que contiene binarios de plugin (promtail, otelcol-contrib, node_exporter, process_exporter).
ONGRID_EDGE_PLUGIN_WORK_DIR	string	/var/lib/ongrid-edge/plugins	Dirs runtime por-plugin (configs, archivos PID, queue spool).
ONGRID_EDGE_UPGRADE_STAGE_DIR	string	/var/lib/ongrid-edge/.upgrade	Directorio de bundle staged de ADR-024. Vacío deshabilita upgrades de whole-bundle remotos.
ONGRID_INSTALL_WAIT	int	20	Segundos que el installer curl-pipe sondea el journal esperando "registered with cloud".

---

Embedding & RAG

Variable	Tipo	Default	Descripción
ONGRID_EMBEDDING_PROVIDER	string	zhipu	zhipu (default; llama a la API de embedding de GLM), local (usa un modelo bge en disco), openai (usa embeddings de OpenAI).
ONGRID_EMBEDDING_LOCAL_MODEL_PATH	string	empty	Path absoluto al modelo local cuando PROVIDER=local. El tarball de release stagea bge-base-en-v1.5 bajo .cache/.
ONGRID_VAULT_REPO_URL	string	https://github.com/ongridio/vault	Repositorio upstream del vault del que el manager jala conocimiento baseline. Sobrescribe para mirrors air-gapped.

---

Locale & misc

Variable	Tipo	Default	Descripción
ONGRID_DEFAULT_LOCALE	string	en	Locale default usado por salidas automáticas del LLM (investigaciones de alertas, resúmenes programados). El chat triggered por UI usa el locale UI del usuario en su lugar.

---

Ver también

• REST API — endpoints que estas env vars cablean.
• CLI — flags de línea de comandos de los dos binarios.
• Data plane de telemetría — por qué los endpoints de log/traza difieren del túnel.
• Arquitectura — dónde vive cada env var en el diagrama del stack.