환경 변수
ongrid 와 ongrid-edge 둘 다 환경 변수로만 구성됩니다. YAML 없음. 정규 와이어링은 internal/pkg/config/config.go 와 deploy/docker-compose.yml 의 compose env 블록에 있습니다. 아래의 모든 변수는 기동 시 읽힙니다 — 매니저는 hot-reload 하지 않습니다.
표는 변수를 서브시스템별로 그룹핑합니다. 보여 주는 기본값은 변수가 설정되지 않았거나 비어 있을 때 바이너리가 고르는 값입니다. "필수" 는 "1열의 기능이 이것 없이 동작하지 않는다" 를 의미합니다.
HTTP & 메트릭 listener
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_HTTP_ADDR | string | :8080 | API + SPA 의 TCP listen. compose 스택의 nginx 가 /api/* 를 여기로 프록시. |
ONGRID_METRICS_ADDR | string | :9100 | /metrics 의 TCP listen. Prometheus 가 스크레이프. |
ONGRID_TUNNEL_ADDR | string | :40012 | Geminio 브로커 listen. 매니저 자체가 아니라 frontier 서비스가 바인드. |
ONGRID_PUBLIC_URL | string | empty | edge 에 데이터 플레인 엔드포인트 (로그/트레이스 ingest, edge 번들 다운로드) 로 전달되는 정규 https://... URL. 비어 있으면 데이터 플레인 플러그인 엔드포인트가 비활성화. 프로덕션에서는 반드시 설정. |
데이터베이스 (MySQL 기본, SQLite opt-in)
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_DB_DIALECT | string | mysql | mysql (기본) 또는 sqlite. 비어 있으면 mysql 로 취급. |
ONGRID_DB_DSN | string | ongrid:ongrid@tcp(127.0.0.1:3306)/ongrid?parseTime=true&charset=utf8mb4&loc=Local | MySQL DSN. 프로덕션 필수. |
ONGRID_DB_PATH | string | ./data/ongrid.db | SQLite 데이터베이스 파일 경로. 테스트에서 :memory: 허용. |
JWT (iam)
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_JWT_SECRET | string | dev-insecure-secret-change-me | access + refresh 토큰의 HS256 서명 키. 필수; 기본값으로는 프로덕션 빌드에서 토큰 발급을 거부함. |
ONGRID_JWT_ACCESS_TTL | duration | 15m | Access 토큰 TTL. |
ONGRID_JWT_REFRESH_TTL | duration | 168h (7d) | Refresh 토큰 TTL. |
Duration 은 Go time.ParseDuration 문법 (15m, 2h, 30s) 을 받습니다. 단순 정수는 초로 해석됩니다.
LLM 제공자
chat 에이전트는 6개의 일급 제공자와 Custom (OpenAI 호환) 슬롯을 지원합니다. 각 제공자는 자체 API 키로 게이팅됩니다 — 빈 키 = 제공자가 chat picker 에 노출되지 않음.
OpenAI
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_OPENAI_API_KEY | string | empty | OpenAI API 키. 비어 있으면 picker 에서 OpenAI 가 숨겨짐. |
ONGRID_OPENAI_MODEL | string | gpt-5.4 | OpenAI 가 선택된 제공자일 때의 기본 모델. |
ONGRID_OPENAI_BASE_URL | string | empty | OpenAI 호환 릴레이 (Azure / vLLM / Ollama / one-api) 용 base URL 오버라이드. |
Anthropic, Zhipu, Gemini, DeepSeek, Kimi
각 제공자는 같은 세 개의 키 (API 키 / 기본 모델 / base URL) 와 네 번째 (MODELS, 선택 가능한 모델 슬러그의 콤마 구분 리스트) 를 갖습니다:
| 변수 | 기본값 |
|---|---|
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 |
라우팅 & 예산
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_LLM_DEFAULT_PROVIDER | string | empty | 요청이 제공자를 지정하지 않을 때 쓰이는 제공자. 비어 있으면 첫 번째로 구성된 제공자 (알파벳순). 특정 제공자를 사이트 기본값으로 만들고 싶을 때 설정. |
ONGRID_LLM_DAILY_TOKEN_LIMIT | int | 0 | UTC 일자별 글로벌 토큰 상한. 0 = 무제한. |
에이전트 커널 & 도구
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_AGENT_KERNEL | string | graph | graph 는 eino 그래프 커널 + SkillRegistry.Resolve 활성화 키워드 필터 + ToolBag deferral 파이프라인을 활성화. legacy 는 모든 도구를 full schema 로 두는 구식 for-loop 러너. 이등분 (bisect) 용으로만 legacy 로 전환. |
ONGRID_TOOLBAG_DEFERRAL_THRESHOLD | int | 30 | 이 임계값 이상이면 specialty 등급 도구의 스키마를 redact (LLM 이 확장하려면 ToolSearch 를 호출해야 함). |
ONGRID_SKILLS_EXTERNAL_DIRS | csv | empty | skill 로더가 skill.json 매니페스트를 스캔하는 콤마/콜론 구분 절대 경로. 각각 절대 경로여야 함; 상대 경로나 누락된 항목은 로그 라인과 함께 건너뜀. |
Frontier 브로커 클라이언트
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_FRONTIER_ADDR | string | frontier:40011 | 매니저가 dial 하는 업스트림 frontier 브로커의 service-bound listen. |
ONGRID_FRONTIER_SERVICE_NAME | string | ongrid-manager | 연결 시 보고되는 식별자. |
ONGRID_FRONTIER_DISABLED | bool | false | 장기 service-end dial 을 완전 건너뜀. e2e 하니스용 — 브로커가 필요한 기능 (webssh, edge 역호출) 은 호출 지점에서 에러. |
클라우드측 Prometheus
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_PROM_ENABLED | bool | false | Prometheus 와이어링 게이트. false 면 매니저가 메트릭 저장 없이 실행 — push_prom_samples 가 조용히 drop, query_promql 가 도구로 등록되지 않음. |
ONGRID_PROM_URL | string | http://prometheus:9090 | Prom 서버 루트 URL. |
ONGRID_PROM_REMOTE_WRITE_URL | string | empty | 업스트림이 /api/v1/write 에 루트가 없을 때의 정확한 remote_write 엔드포인트 (Mimir / Cortex / VictoriaMetrics 게이트웨이). |
ONGRID_PROM_QUERY_URL | string | empty | query_promql 의 Query API 루트. 비어 있으면 ONGRID_PROM_URL 로 폴백. |
ONGRID_PROM_TLS_INSECURE | bool | false | TLS 인증서 검증 건너뜀. |
ONGRID_PROM_TLS_CA_FILE | string | empty | TSDB 의 인증서를 검증할 root CA 의 PEM 파일. 비어 있으면 시스템 루트. |
Grafana
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_GRAFANA_INTERNAL_URL | string | http://grafana:3000/grafana | 매니저가 docker 네트워크로 Grafana 에 도달하는 URL. |
ONGRID_GRAFANA_BOOTSTRAP_USER | string | admin | ongrid Service Account + 토큰을 자동 생성하는 일회용 admin 사용자. |
ONGRID_GRAFANA_BOOTSTRAP_PASSWORD | string | empty | 부트스트랩 비밀번호. 비어 있으면 부트스트랩 비활성 (UI 에 수동 생성된 SA 토큰을 붙임). |
ONGRID_GRAFANA_TLS_INSECURE | bool | false | 부트스트랩 호출의 인증서 검증 건너뜀. |
ONGRID_GRAFANA_ROOT_URL | string | %(protocol)s://%(domain)s/grafana/ | GF_SERVER_ROOT_URL 로 포워딩. |
로그 & 트레이스 (데이터 플레인)
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_LOG_QUERY_URL | string | http://loki:3100 | 매니저가 query_range / labels / values 에 대해 대화하는 Loki API 루트. 비어 있으면 Logs 페이지가 503 반환. |
ONGRID_TRACE_QUERY_URL | string | http://tempo:3200 | /api/search, /api/traces/<id>, /api/search/tag/<tag>/values 용 Tempo HTTP listener 루트. 비어 있으면 Traces 페이지가 503 반환. |
edge 데이터 플레인 엔드포인트 (로그/트레이스 플러그인이 POST 하는 곳) 는 ONGRID_PUBLIC_URL 에서 도출됩니다 — 텔레메트리 데이터 플레인 참고.
빌트인 알림 임계값
이들은 호스트 메트릭 폐쇄형 집합 위에서 네 개의 정규 빌트인 규칙을 구동합니다. 비활성에는 0 으로 설정.
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_ALERT_ENABLED | bool | true | 빌트인 호스트 알림 평가의 마스터 스위치. |
ONGRID_ALERT_COOLDOWN | duration | 10m | (edge, rule) 별 cooldown. 이 윈도 안의 알림은 억제. |
ONGRID_ALERT_CPU_PERCENT | float | 90 | cpu_pct >= threshold 시 발생. |
ONGRID_ALERT_MEM_PERCENT | float | 90 | mem_pct >= threshold 시 발생. |
ONGRID_ALERT_DISK_USED_PERCENT | float | 90 | disk_used_pct >= threshold 시 발생. |
ONGRID_ALERT_LOAD1 | float | 0 | load1 >= threshold 시 발생. 0 은 비활성 (load 는 호스트 모양에 따라 너무 변동이 커서 유용한 기본값이 없음). |
ONGRID_ALERT_EVAL_INTERVAL | duration | 5m | 파이프라인 evaluator 가 edge 를 스캔하고 Prom 을 질의하는 주기. |
ONGRID_ALERT_EDGE_OFFLINE_THRESHOLD | duration | 90s | 하트비트 신선도가 이 시간을 넘으면 edge 가 offline 으로 카운트. |
ONGRID_ALERT_PROM_INGEST_FAIL_LIMIT | int | 5 | prom_ingest_fail 이 발생하는 연속 remote_write 실패 횟수. |
알림 (Notifications)
마스터 스위치 + 네 개의 빌트인 채널 타입. UI 로 생성된 채널은 자체 enabled 플래그를 가지고 이 영향을 받지 않습니다.
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_NOTIFY_ENABLED | bool | true | 아웃바운드 알림의 마스터 스위치. |
ONGRID_NOTIFY_DEFAULT_CHANNELS | csv | empty | 호출자가 대상을 지정하지 않을 때 쓰이는 채널 이름 순서 목록. |
ONGRID_NOTIFY_TIMEOUT | duration | 10s | 채널당 전송 타임아웃. |
ONGRID_NOTIFY_WEBHOOK_ENABLED | bool | false | env 구성 webhook 채널 활성. |
ONGRID_NOTIFY_WEBHOOK_NAME | string | webhook | 표시 이름. |
ONGRID_NOTIFY_WEBHOOK_URL | string | empty | POST 엔드포인트. |
ONGRID_NOTIFY_WEBHOOK_SECRET | string | empty | 선택적 HMAC secret. |
ONGRID_NOTIFY_SLACK_ENABLED | bool | false | env 구성 Slack 채널 활성. |
ONGRID_NOTIFY_SLACK_NAME | string | slack | 표시 이름. |
ONGRID_NOTIFY_SLACK_WEBHOOK_URL | string | empty | Incoming Webhook URL. |
ONGRID_NOTIFY_FEISHU_ENABLED | bool | false | env 구성 Larksuite / Feishu 채널 활성. |
ONGRID_NOTIFY_FEISHU_NAME | string | feishu | 표시 이름. |
ONGRID_NOTIFY_FEISHU_WEBHOOK_URL | string | empty | Custom-Bot URL. |
ONGRID_NOTIFY_FEISHU_SECRET | string | empty | 서명 secret. |
ONGRID_NOTIFY_DINGTALK_ENABLED | bool | false | env 구성 DingTalk 채널 활성. |
ONGRID_NOTIFY_DINGTALK_NAME | string | dingtalk | 표시 이름. |
ONGRID_NOTIFY_DINGTALK_WEBHOOK_URL | string | empty | Custom-Bot URL. |
ONGRID_NOTIFY_DINGTALK_SECRET | string | empty | 서명 secret. |
WeCom 과 Telegram 채널은 Settings → Channels UI 에서 만드세요 — 이들도 일급이지만 env 구성 단축이 없습니다.
부트스트랩 admin
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_ADMIN_EMAIL | string | empty | 부트스트랩 admin 의 email. 비어 있으면 admin 이 시드되지 않음; 첫 부팅 시 UI 에서 등록해야 함. |
ONGRID_ADMIN_PASSWORD | string | empty | 초기 비밀번호. 운영자는 첫 로그인 시 변경할 것이 기대됨. |
Edge 에이전트
이들은 ongrid-edge 가 소비하며, 설치 스크립트가 /etc/ongrid-edge/ongrid-edge.env 에 기록합니다.
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_EDGE_CLOUD_ADDR | string | 127.0.0.1:40012 | Frontier 브로커 host:port. 에이전트가 TLS 로 dial. |
ONGRID_EDGE_ACCESS_KEY | string | empty | edge 별 access 키. UI 에서 edge 를 생성할 때 매니저가 발급. |
ONGRID_EDGE_SECRET_KEY | string | empty | 매칭되는 secret. edge 생성 시 한 번 표시; UI 에서 교체. |
ONGRID_EDGE_COLLECTOR_MODE | string | off | off (기본; hostmetrics + procmetrics 플러그인이 메트릭 처리), auto (레거시 내장 + scraper), embedded (내장 push 만), scrape (다중 타깃 HTTP scraper). |
ONGRID_EDGE_SCRAPE_CONFIG_FILE | string | /etc/ongrid-edge/scrape.yaml | scrape config YAML 경로. COLLECTOR_MODE=scrape 일 때만 참조. |
ONGRID_EDGE_COLLECTOR_INTERVAL | duration | 10s | 내장 컬렉터가 스냅샷하는 주기. Scrape 모드는 이를 무시. |
ONGRID_EDGE_PLUGIN_BIN_DIR | string | /usr/local/lib/ongrid-edge | 플러그인 바이너리 (promtail, otelcol-contrib, node_exporter, process_exporter) 가 있는 디렉터리. |
ONGRID_EDGE_PLUGIN_WORK_DIR | string | /var/lib/ongrid-edge/plugins | 플러그인별 런타임 디렉터리 (config, PID 파일, 큐 spool). |
ONGRID_EDGE_UPGRADE_STAGE_DIR | string | /var/lib/ongrid-edge/.upgrade | ADR-024 staged-bundle 디렉터리. 비어 있으면 원격 whole-bundle 업그레이드 비활성. |
ONGRID_INSTALL_WAIT | int | 20 | curl-pipe 설치 스크립트가 "registered with cloud" 를 기다리며 journal 을 폴링하는 초. |
임베딩 & RAG
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_EMBEDDING_PROVIDER | string | zhipu | zhipu (기본; GLM 임베딩 API 호출), local (디스크의 bge 모델 사용), openai (OpenAI 임베딩 사용). |
ONGRID_EMBEDDING_LOCAL_MODEL_PATH | string | empty | PROVIDER=local 일 때 로컬 모델의 절대 경로. 릴리스 tarball 은 .cache/ 아래에 bge-base-en-v1.5 를 스테이징. |
ONGRID_VAULT_REPO_URL | string | https://github.com/ongridio/vault | 매니저가 기본 지식을 pull 하는 업스트림 vault 저장소. 에어갭 미러용으로 오버라이드. |
Locale & 기타
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ONGRID_DEFAULT_LOCALE | string | en | 자동 LLM 출력 (알림 조사, 스케줄된 요약) 이 사용하는 기본 locale. UI 트리거 chat 은 사용자의 UI locale 을 대신 사용. |
함께 보기
- REST API — 이 env 변수들이 와이어업하는 엔드포인트.
- CLI — 두 바이너리의 커맨드라인 플래그.
- 텔레메트리 데이터 플레인 — 로그/트레이스 엔드포인트가 터널과 다른 이유.
- Architecture — 스택 다이어그램에서 각 env 변수가 어디 사는지.