Variáveis de ambiente

Tanto ongrid quanto ongrid-edge são configurados exclusivamente através de variáveis de ambiente. Sem YAML. A fiação canônica vive em internal/pkg/config/config.go e o bloco env do compose em deploy/docker-compose.yml. Cada variável abaixo é lida no startup; o manager não faz hot-reload.

Tabelas agrupam variáveis por subsistema. Defaults mostrados são o que o binário escolhe quando a variável não está setada ou vazia. "Obrigatório" significa "a feature na coluna 1 não funcionará sem ele".

---

Listeners HTTP & metrics

Variável	Tipo	Padrão	Descrição
ONGRID_HTTP_ADDR	string	:8080	Listen TCP para a API + SPA. nginx na stack compose proxia /api/* aqui.
ONGRID_METRICS_ADDR	string	:9100	Listen TCP para /metrics. Raspado pelo Prometheus.
ONGRID_TUNNEL_ADDR	string	:40012	Listen do broker Geminio. Vinculado pelo serviço frontier, não pelo próprio manager.
ONGRID_PUBLIC_URL	string	vazio	URL canônica https://... que o manager passa aos edges como endpoint de data-plane (ingest de logs/traces, download de bundle do edge). Vazio desabilita endpoints de plugin do data plane. Defina em produção.

---

Database (MySQL padrão, SQLite opt-in)

Variável	Tipo	Padrão	Descrição
ONGRID_DB_DIALECT	string	mysql	mysql (padrão) ou sqlite. Vazio é tratado como mysql.
ONGRID_DB_DSN	string	ongrid:ongrid@tcp(127.0.0.1:3306)/ongrid?parseTime=true&charset=utf8mb4&loc=Local	DSN MySQL. Obrigatório em produção.
ONGRID_DB_PATH	string	./data/ongrid.db	Path do arquivo de DB SQLite. :memory: é aceito em testes.

---

JWT (iam)

Variável	Tipo	Padrão	Descrição
ONGRID_JWT_SECRET	string	dev-insecure-secret-change-me	Chave de assinatura HS256 para access + refresh tokens. Obrigatório; o padrão recusa emitir tokens em builds de produção.
ONGRID_JWT_ACCESS_TTL	duration	15m	TTL de access-token.
ONGRID_JWT_REFRESH_TTL	duration	168h (7d)	TTL de refresh-token.

Durations aceitam sintaxe time.ParseDuration do Go (15m, 2h, 30s). Um integer puro é interpretado como segundos.

---

Providers LLM

O chat agent suporta seis providers first-class mais um slot Custom (compatível com OpenAI). Cada provider é gateado por sua API key — chave vazia = provider não exposto ao picker de chat.

OpenAI

Variável	Tipo	Padrão	Descrição
ONGRID_OPENAI_API_KEY	string	vazio	API key OpenAI. Vazio = OpenAI escondido do picker.
ONGRID_OPENAI_MODEL	string	gpt-5.4	Modelo padrão quando OpenAI é o provider selecionado.
ONGRID_OPENAI_BASE_URL	string	vazio	Override de base URL para relays compatíveis com OpenAI (Azure / vLLM / Ollama / one-api).

Anthropic, Zhipu, Gemini, DeepSeek, Kimi

Cada provider tem as mesmas três chaves (API key / modelo padrão / base URL) e uma quarta (MODELS, lista separada por vírgula de slugs de modelo selecionáveis):

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

Roteamento & budget

Variável	Tipo	Padrão	Descrição
ONGRID_LLM_DEFAULT_PROVIDER	string	vazio	Provider usado quando uma request não especifica um. Vazio = primeiro provider configurado (alfabético). Defina quando você quer um provider específico como default do site.
ONGRID_LLM_DAILY_TOKEN_LIMIT	int	0	Teto global de token por dia UTC. 0 = ilimitado.

---

Agent kernel & tools

Variável	Tipo	Padrão	Descrição
ONGRID_AGENT_KERNEL	string	graph	graph habilita o kernel de grafo eino + filtro de activation-keyword SkillRegistry.Resolve + pipeline de deferral ToolBag. legacy é o runner de for-loop mais antigo com todas as tools sempre full-schema. Vire para legacy só para bisect.
ONGRID_TOOLBAG_DEFERRAL_THRESHOLD	int	30	Threshold de contagem de tool acima do qual tools de specialty-tier ganham schemas redacted (LLM precisa chamar ToolSearch para expandir).
ONGRID_SKILLS_EXTERNAL_DIRS	csv	vazio	Paths absolutos separados por vírgula/dois-pontos que o loader de skill escaneia por manifestos skill.json. Cada um precisa ser absoluto; entradas relativas ou faltantes são puladas com linha de log.

---

Client do broker Frontier

Variável	Tipo	Padrão	Descrição
ONGRID_FRONTIER_ADDR	string	frontier:40011	Listen vinculado a serviço do broker frontier upstream que o manager disca.
ONGRID_FRONTIER_SERVICE_NAME	string	ongrid-manager	Identificador reportado no connect.
ONGRID_FRONTIER_DISABLED	bool	false	Pula o dial service-end de longa duração inteiramente. Usado pelo harness e2e — features que requerem o broker (webssh, calls reversos do edge) erram no call site.

---

Prometheus cloud-side

Variável	Tipo	Padrão	Descrição
ONGRID_PROM_ENABLED	bool	false	Gateia a fiação Prometheus. Quando false o manager roda sem armazenamento de métrica; push_prom_samples silenciosamente descarta, e query_promql não é registrado como tool.
ONGRID_PROM_URL	string	http://prometheus:9090	URL raiz do server Prom.
ONGRID_PROM_REMOTE_WRITE_URL	string	vazio	Endpoint exato de remote_write quando o upstream não tem raiz em /api/v1/write (gateway Mimir / Cortex / VictoriaMetrics).
ONGRID_PROM_QUERY_URL	string	vazio	Raiz da API de query para query_promql. Vazio cai para ONGRID_PROM_URL.
ONGRID_PROM_TLS_INSECURE	bool	false	Pula verificação de cert TLS.
ONGRID_PROM_TLS_CA_FILE	string	vazio	Arquivo PEM com a CA raiz usada para verificar o cert do TSDB. Vazio = roots do sistema.

---

Grafana

Variável	Tipo	Padrão	Descrição
ONGRID_GRAFANA_INTERNAL_URL	string	http://grafana:3000/grafana	URL que o manager usa para alcançar o Grafana pela rede docker.
ONGRID_GRAFANA_BOOTSTRAP_USER	string	admin	User admin one-time usado para auto-criar o Service Account ongrid + token.
ONGRID_GRAFANA_BOOTSTRAP_PASSWORD	string	vazio	Senha de bootstrap; vazio desabilita bootstrap (cole um token SA criado manualmente na UI).
ONGRID_GRAFANA_TLS_INSECURE	bool	false	Pula verificação de cert para o call de bootstrap.
ONGRID_GRAFANA_ROOT_URL	string	%(protocol)s://%(domain)s/grafana/	Encaminhado para GF_SERVER_ROOT_URL.

---

Logs & traces (data plane)

Variável	Tipo	Padrão	Descrição
ONGRID_LOG_QUERY_URL	string	http://loki:3100	Raiz da API Loki que o manager fala para query_range / labels / values. Vazio = página Logs retorna 503.
ONGRID_TRACE_QUERY_URL	string	http://tempo:3200	Raiz do listener HTTP do Tempo para /api/search, /api/traces/<id>, /api/search/tag/<tag>/values. Vazio = página Traces retorna 503.

Os endpoints de data plane do edge (onde os plugins de logs / traces fazem POST) são derivados de ONGRID_PUBLIC_URL; veja Data plane de telemetria.

---

Thresholds de alertas built-in

Esses dirigem as quatro rules canônicas built-in sobre o conjunto fechado de métrica de host. Defina como 0 para desabilitar.

Variável	Tipo	Padrão	Descrição
ONGRID_ALERT_ENABLED	bool	true	Switch mestre para avaliação de alerta de host built-in.
ONGRID_ALERT_COOLDOWN	duration	10m	Cooldown por-(edge, rule). Notificações dentro dessa janela são suprimidas.
ONGRID_ALERT_CPU_PERCENT	float	90	Dispara quando cpu_pct >= threshold.
ONGRID_ALERT_MEM_PERCENT	float	90	Dispara quando mem_pct >= threshold.
ONGRID_ALERT_DISK_USED_PERCENT	float	90	Dispara quando disk_used_pct >= threshold.
ONGRID_ALERT_LOAD1	float	0	Dispara quando load1 >= threshold. 0 desabilita (load varia demais entre formatos de host para um default útil).
ONGRID_ALERT_EVAL_INTERVAL	duration	5m	Com que frequência o pipeline evaluator escaneia edges e consulta Prom.
ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD	duration	90s	Staleness de heartbeat acima da qual um edge conta como offline.
ONGRID_ALERT_PROM_INGEST_FAIL_LIMIT	int	5	Contagem consecutiva de falha remote_write na qual prom_ingest_fail dispara.

---

Notificações

Switch mestre + os quatro tipos de canal built-in. Canais criados pela UI carregam sua própria flag enabled e são não-afetados por esses.

Variável	Tipo	Padrão	Descrição
ONGRID_NOTIFY_ENABLED	bool	true	Switch mestre para notificações outbound.
ONGRID_NOTIFY_DEFAULT_CHANNELS	csv	vazio	Lista ordenada de channel-name usada quando um caller não especifica destinos.
ONGRID_NOTIFY_TIMEOUT	duration	10s	Timeout de envio por-canal.
ONGRID_NOTIFY_WEBHOOK_ENABLED	bool	false	Habilita o canal webhook env-configurado.
ONGRID_NOTIFY_WEBHOOK_NAME	string	webhook	Nome de display.
ONGRID_NOTIFY_WEBHOOK_URL	string	vazio	Endpoint POST.
ONGRID_NOTIFY_WEBHOOK_SECRET	string	vazio	Secret HMAC opcional.
ONGRID_NOTIFY_SLACK_ENABLED	bool	false	Habilita o canal Slack env-configurado.
ONGRID_NOTIFY_SLACK_NAME	string	slack	Nome de display.
ONGRID_NOTIFY_SLACK_WEBHOOK_URL	string	vazio	URL Incoming Webhook.
ONGRID_NOTIFY_FEISHU_ENABLED	bool	false	Habilita o canal Larksuite / Feishu env-configurado.
ONGRID_NOTIFY_FEISHU_NAME	string	feishu	Nome de display.
ONGRID_NOTIFY_FEISHU_WEBHOOK_URL	string	vazio	URL Custom-Bot.
ONGRID_NOTIFY_FEISHU_SECRET	string	vazio	Secret de assinatura.
ONGRID_NOTIFY_DINGTALK_ENABLED	bool	false	Habilita o canal DingTalk env-configurado.
ONGRID_NOTIFY_DINGTALK_NAME	string	dingtalk	Nome de display.
ONGRID_NOTIFY_DINGTALK_WEBHOOK_URL	string	vazio	URL Custom-Bot.
ONGRID_NOTIFY_DINGTALK_SECRET	string	vazio	Secret de assinatura.

Para canais WeCom e Telegram, crie-os pela UI Settings → Channels — são first-class mas não têm shortcut de env-configuração.

---

Admin de bootstrap

Variável	Tipo	Padrão	Descrição
ONGRID_ADMIN_EMAIL	string	vazio	Email do admin de bootstrap. Se vazio, nenhum admin é semeado; você precisa registrar pela UI no primeiro boot.
ONGRID_ADMIN_PASSWORD	string	vazio	Senha inicial. Esperado que o operador mude no primeiro login.

---

Edge agent

Esses são consumidos por ongrid-edge, escritos em /etc/ongrid-edge/ongrid-edge.env pelo instalador.

Variável	Tipo	Padrão	Descrição
ONGRID_EDGE_CLOUD_ADDR	string	127.0.0.1:40012	Broker frontier host:port. O agent disca isto com TLS.
ONGRID_EDGE_ACCESS_KEY	string	vazio	Access key por-edge. Emitida pelo manager quando você cria um edge na UI.
ONGRID_EDGE_SECRET_KEY	string	vazio	Secret correspondente. Mostrada uma vez na criação do edge; rotacione pela UI.
ONGRID_EDGE_COLLECTOR_MODE	string	off	off (padrão; os plugins hostmetrics + procmetrics tratam métricas), auto (legado embarcado + scraper), embedded (push embarcado apenas), scrape (scraper HTTP multi-target).
ONGRID_EDGE_SCRAPE_CONFIG_FILE	string	/etc/ongrid-edge/scrape.yaml	Path para o YAML de config de scrape. Só consultado quando COLLECTOR_MODE=scrape.
ONGRID_EDGE_COLLECTOR_INTERVAL	duration	10s	Com que frequência o collector embarcado faz snapshots. Modo scrape ignora isto.
ONGRID_EDGE_PLUGIN_BIN_DIR	string	/usr/local/lib/ongrid-edge	Diretório contendo binários de plugin (promtail, otelcol-contrib, node_exporter, process_exporter).
ONGRID_EDGE_PLUGIN_WORK_DIR	string	/var/lib/ongrid-edge/plugins	Dirs de runtime por-plugin (configs, arquivos PID, queue spool).
ONGRID_EDGE_UPGRADE_STAGE_DIR	string	/var/lib/ongrid-edge/.upgrade	Diretório de staged-bundle do ADR-024. Vazio desabilita upgrades remotos de whole-bundle.
ONGRID_INSTALL_WAIT	int	20	Segundos que o instalador curl-pipe faz polling no journal esperando por "registered with cloud".

---

Embedding & RAG

Variável	Tipo	Padrão	Descrição
ONGRID_EMBEDDING_PROVIDER	string	zhipu	zhipu (padrão; chama a API de embedding GLM), local (usa um modelo bge em disco), openai (usa embeddings OpenAI).
ONGRID_EMBEDDING_LOCAL_MODEL_PATH	string	vazio	Path absoluto para o modelo local quando PROVIDER=local. O tarball de release stage bge-base-en-v1.5 sob .cache/.
ONGRID_VAULT_REPO_URL	string	https://github.com/ongridio/vault	Repositório vault upstream do qual o manager puxa conhecimento baseline. Sobrescreva para mirrors air-gapped.

---

Locale & misc

Variável	Tipo	Padrão	Descrição
ONGRID_DEFAULT_LOCALE	string	en	Locale padrão usado por saídas LLM automáticas (investigações de alerta, sumários agendados). Chat disparado pela UI usa o locale da UI do usuário em vez disso.

---

Veja também

• REST API — endpoints que essas env vars conectam.
• CLI — flags de linha de comando dos dois binários.
• Data plane de telemetria — por que endpoints de log/trace diferem do tunnel.
• Arquitetura — onde cada env var vive no diagrama de stack.