Biến môi trường — tra cứu theo nhóm

Tham chiếu đầy đủ 25 biến nằm ở ai-agent-board/.env.example trong repo. Trang này nhóm các biến theo chức năng và hậu quả khi thiếu/sai — đọc thêm Cài đặt và Vận hành hằng ngày.

Danh tính & phân quyền (server từ chối boot nếu không có cách nào)

Biến	Ý nghĩa
CF_ACCESS_AUD + CF_ACCESS_TEAM_DOMAIN	Verify JWT Cloudflare Access (production khuyến nghị)
TRUST_PROXY_IDENTITY=1 + TRUSTED_PROXY_IPS	Tin x-forwarded-email — chỉ từ IP proxy liệt kê (dev: nginx 172.28.240.10)
AGENTBOARD_DEV_IDENTITY=1	Bypass mọi request thành owner — chỉ DEV-LITE; cấm đi cùng NODE_ENV=production
AGENTBOARD_BOOTSTRAP_OWNERS	Email owner khởi tạo / break-glass (idempotent)
API_KEY / VITE_API_KEY	Bearer token cho API + WebSocket (phải khớp nhau; unset = open access, chỉ dev)
SERVICE_TOKENS	JSON service credentials có scope (không bao giờ approve được)

Không bật đồng thời AGENTBOARD_DEV_IDENTITY và TRUST_PROXY_IDENTITY — server báo

Conflicting identity configuration khi boot.

Arkon & tri thức (bắt buộc ở mọi môi trường container)

Biến	Thiếu/sai thì sao
ARKON_SSO_SHARED_SECRET = SSO_SHARED_SECRET (Arkon)	Provisioning 403 → tạo Space 500 (host qua cổng published không phải loopback)
ARKON_ENCRYPTION_KEY	Production từ chối boot (mã hoá MCP token at-rest)
ARKON_API_URL	Sai/mặc định loopback → Wiki chết lặng
MINIO_ENDPOINT (không dấu _)	Dấu _ → InvalidRequest: invalid hostname, mọi upload/ảnh wiki chết

AI Planner & Reviewer (LLM)

Biến	Ý nghĩa
AGENTBOARD_LLM_MODE	replay (mặc định, test/CI) · record (ghi cassette) · live (dev thực tế & production)
AGENTBOARD_LLM_API_KEY + AGENTBOARD_LLM_MODEL	Bắt buộc ở mode live (model không có default); OpenRouter qua AGENTBOARD_LLM_BASE_URL
AGENTBOARD_LLM_TIMEOUT_MS	Timeout gọi LLM (mặc định 60000)
AGENTBOARD_LLM_FIXTURES_DIR	Thư mục cassette cho mode replay/record
AGENTBOARD_REVIEWER_AGENT	auto (mặc định, cần LLM thật) · heuristic (E2E) · off
AGENTBOARD_WIKI_CONTEXT / AGENTBOARD_BOARD_REPAIR	Kill-switch bơm Wiki / repair loop (=0 để tắt)

Cờ Chặng 0B (Arkon substrate) — 8 cờ, mặc định TẮT

TẮT một cờ = rollback trọn vẹn tính năng đó, không cần đổi image. Truthy: 1 / true / on / yes (không phân biệt hoa thường) — mọi giá trị khác, kể cả rỗng, là TẮT.

Biến	Bật được gì	Cần kèm theo
AGENTBOARD_ARKON_SOURCES	Nạp tài liệu /api/sources/* + pipeline MRP + 2 cổng người duyệt	Key LLM thật (MRP gọi model)
AGENTBOARD_WIKI_LINKS	Liên kết Task ⇄ trang wiki lưu bền (task_wiki_links)	—
AGENTBOARD_UNIFIED_REVIEW_QUEUE	Hàng đợi duyệt gộp Code + Wiki (chỉ client)	—
AGENTBOARD_WIKI_DEEP_UI	8 route wiki sâu (revisions, rollback, graph, lint, branches + merge/close) — gác cả API lẫn UI: tắt = toàn bộ 404	—
AGENTBOARD_ARKON_USER_TOKENS	Lời gọi Arkon mang danh tính thật của user, hết admin@arkon.local	—
AGENTBOARD_ARKON_RBAC_SYNC	Đồng bộ role Space → global_role Arkon + reconciler định kỳ	—
AGENTBOARD_ARKON_RBAC_RECONCILE_MS	Nhịp reconciler; rỗng = 15 phút	Chỉ có ý nghĩa khi …_RBAC_SYNC bật
AGENTBOARD_ARKON_PERSONA_TOKENS	Đề xuất wiki của agent ký @architect / @qa / …	Task có cột persona
AGENTBOARD_ARKON_MCP	Bơm credential MCP vào worktree mỗi run, thu hồi sau run	Agent thật (không fake)

Cờ Chặng 0C (board-polish) — 4 cờ + 1 nhịp, mặc định TẮT

Biến	Bật được gì	Cần kèm theo
AGENTBOARD_COMMAND_PALETTE	Palette Cmd+K / Ctrl+K (chỉ client)	—
AGENTBOARD_MENTION_SUBTASK	@persona <việc> trong comment sinh subtask + tab Comments	—
AGENTBOARD_AUTO_RETRO	Epic xong hết con → thảo Retrospective chờ duyệt	Space đã nối Arkon + LLM live
AGENTBOARD_AUTO_RETRO_SWEEP_MS	Nhịp quét lại retro hỏng; rỗng = 15 phút, sàn cứng 30s	Chỉ có ý nghĩa khi …_AUTO_RETRO bật
AGENTBOARD_WS_TOPICS	WebSocket chia room theo Space	⚠️ Bắt buộc AGENT_BOARD_PUBLIC_URL đã khai và host của nó nằm trong ALLOWED_HOSTS — thiếu thì server từ chối boot (fatal preflight)

Đặt cờ trong .env là chưa đủ — phải tới được container

Cả 8 cờ 0B từng "đúng code, xanh test mà không bật được" vì thiếu trong environment: của compose. Sau mọi sửa env, kiểm từ trong container, không tin file:

docker exec agentjira_server printenv | grep AGENTBOARD_
curl -s localhost:8081/api/features   # phải phản ánh đúng ý định

Chi tiết đầy đủ: INSTALLATION.md (khối cờ 0B/0C), RUNBOOK.md §2/§2.1/§6.

Agent runtime & mạng

Biến	Ý nghĩa
ALLOWED_REPO_ROOTS	Agent chỉ được chạm các root này (production: /home/node/agentboard/projects)
AGENTBOARD_HOME	Home của agent runtime trong container
AGENT_TIMEOUT_MS	Timeout mặc định mỗi task (60 phút; task override 1–240 phút)
AGENTBOARD_FAKE_AGENT=1	ScriptedProvider tất định cho E2E — viết file thật, sinh result.json hợp lệ, không cần API key
HERMES_COMMAND	Đổi lệnh khởi động Hermes ACP
COPILOT_MODEL / CLAUDE_MODEL / CODEX_MODEL	Model cho từng provider SDK
ALLOWED_HOSTS / ALLOWED_ORIGINS	Thiếu hostname công khai → WS 403, mất realtime
RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX	Mặc định 3000 req/phút/IP (0 = tắt)
DATABASE_URL	Có = PostgreSQL; bỏ = SQLite local (packages/server/data/agentboard.db)