Environment variables
The server takes all its settings from the environment. The agent takes almost none: its settings are in its config file, and the variables below only move folders, answer prompts or carry a run’s context.
Every variable the server or the agent reads is checked against this page by tests
(apps/server/test/reference-docs.test.ts, apps/agent/src/reference-docs.test.ts). .env.example at the repository
root has a commented template.
The server
Required
| Variable | What it is |
|---|---|
DATABASE_URL |
Postgres for every request’s queries. A transaction pooler is fine. POSTGRES_URL is read when it’s unset. |
DATABASE_URL_DIRECT |
A direct or session-mode connection, for migrations and LISTEN. Defaults to DATABASE_URL. DATABASE_URL_UNPOOLED and POSTGRES_URL_NON_POOLING (set by Vercel’s Neon and Supabase integrations) are read too. |
ANDON_SECRET_KEY |
32 random bytes, base64 (openssl rand -base64 32) or 64 hex digits. The sign-in secret, the key for stored secrets and signed file links all come from it. |
ANDON_SETUP_TOKEN |
What /setup asks for before it creates the first owner. Unset, one is derived from ANDON_SECRET_KEY and printed in the server’s log until setup is done. |
ANDON_SETUP_LOOPBACK |
on: a setup sent straight to localhost, through no proxy, needs no setup token. andon up sets it; leave it unset on a server. Ignored on Vercel. |
Address and sign-in
| Variable | What it is |
|---|---|
ANDON_URL |
Where the server is reached: https://andon.example.com. Unset, the platform’s own address (below), else http://localhost:<PORT>. |
ANDON_BOARD_ORIGINS |
Other origins the board is served from, comma-separated. Sign-ins and passkeys work on each, and a link the server hands back to a request on one is built on it. |
ANDON_SECRET_KEY_PREVIOUS |
Old keys, comma-separated, while you rotate the secret key. |
ALLOW_SIGNUPS |
true: anyone may sign up. Otherwise only an address with an open invite. A new account joins the instance’s one org by invite: an instance holds one org, and /setup makes it. |
TURNSTILE_SECRET_KEY |
A Cloudflare Turnstile secret: signing up, a password sign-in and every request that emails a code (a sign-in code, a new confirmation code, a password reset) need a passed check. Build the board with the matching VITE_TURNSTILE_SITE_KEY, or those sign-ins all fail. Passkeys and GitHub, Google or Apple sign-in need none. Unset: off. |
SMTP_URL |
smtp(s)://user:pass@host:port. Without it no email is sent, and codes and links go to the server’s log. |
MAIL_FROM |
The sender. Default Andon <no-reply@<host>>. |
ANDON_MAIL_LOG |
A file every email is also appended to, one JSON line each (local runs and tests). |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
Sign in with GitHub. Callback: <ANDON_URL>/api/auth/callback/github. |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
Sign in with Google. |
APPLE_CLIENT_ID, APPLE_CLIENT_SECRET, APPLE_APP_BUNDLE_IDENTIFIER |
Sign in with Apple. |
ANDON_IP_HEADERS |
Behind a proxy you trust, the header with the client’s IP, for sign-in rate limits (Caddy: x-forwarded-for). Default: Vercel’s own headers on Vercel, fly-client-ip on Fly, the socket’s address elsewhere. |
ANDON_AUTH_RATE_LIMIT |
off: no sign-in rate limits. For local runs and tests only. |
ANDON_ALLOW_PRIVATE_NETWORK |
true: the trackers (a Jira site), webhook receivers and their redirects may be on private and loopback addresses, for a self-hosted Andon on its own network. Default off: Andon looks up every such host before each request and refuses one that resolves to a private, loopback, link-local or reserved address. Link-local addresses and cloud metadata services are refused either way. |
ANDON_INSTANCE_CONNECT |
Experimental. on: other Andon instances can be connected to this one, and a home instance here keeps its connections (Needs you everywhere). Default off: the connect flow, home’s connections and the rail check answer 404, and connect tokens already granted are refused with 403 until it is on again. A signed-in session (the board, the desktop app) works either way. |
Running it
| Variable | What it is |
|---|---|
PORT |
The Node server’s port. Default 8787. |
HOST |
The addresses it listens on, comma-separated. Default 0.0.0.0. |
ANDON_BOARD_DIR |
The built board to serve. Default apps/board/dist when it exists; off serves the API only. |
ANDON_MAX_ROWS |
The most rows one read returns. Default 1000. |
ANDON_DB_POOL_MAX |
Database connections per server instance. Default 10, 5 on Vercel. |
ANDON_STREAM_MAX_SECONDS |
How long a live-update stream stays open before the client reconnects. Default: unlimited, or 5 under ANDON_MAX_DURATION on Vercel. |
ANDON_MAX_DURATION |
Vercel: the function’s longest run in seconds. Default 300. |
ANDON_TICK_MS |
Node: how often scheduled work runs, in ms. Default 15000; 0 turns the timer off. |
CRON_SECRET |
Vercel: the bearer Vercel Cron sends to /api/cron/tick. Without it the route refuses every call. |
ANDON_CRON |
Vercel: the cron schedule, five fields in UTC. Default 0 4 * * * (daily, Hobby’s most); on Pro, * * * * *. |
File storage
| Variable | What it is |
|---|---|
ANDON_STORAGE |
fs, s3 or vercel-blob. Default: vercel-blob on Vercel, s3 when S3_BUCKET is set, else fs. |
ANDON_STORAGE_DIR |
fs: the folder. Default .andon/storage under the working directory. |
S3_BUCKET |
s3: the bucket. |
S3_ENDPOINT |
s3: the endpoint (R2, B2, MinIO, Supabase Storage). Empty: AWS. |
S3_REGION |
s3: the region. Default AWS_REGION, else us-east-1. |
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY |
s3: the key. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are read when they’re unset. |
S3_FORCE_PATH_STYLE |
s3: <endpoint>/<bucket>/<key> addressing. Default on when S3_ENDPOINT is set. |
S3_PREFIX |
s3: a prefix for every key. |
BLOB_READ_WRITE_TOKEN |
vercel-blob: set by Vercel when a Blob store is connected. |
BLOB_STORE_ID |
vercel-blob: the store, when it’s reached without a token. |
AI features
Each feature uses the deployment’s key unless an org brings its own (Settings → Connections).
| Variable | What it is |
|---|---|
LLM_PROVIDER |
The default backend for model calls: anthropic, gateway, direct or machine (AI backends). Empty: anthropic with an Anthropic key, else direct with a Gemini key, else gateway with a gateway key, else machine. An org’s choice in Settings → Connections wins. |
LLM_MACHINE_TIMEOUT_MS |
How long the app waits for a machine’s answer before its own keys answer. Default 45000. |
ANTHROPIC_API_KEY |
Claude, the default backend: Start Work, Autopilot’s placement, the assistant, attention triage, Auto-Done and recipe detection. Never voice. |
ANTHROPIC_API_BASE |
A fake Anthropic API for local checks. Leave it unset. |
ANTHROPIC_MODEL |
Claude’s model for every feature without its own. Default claude-opus-5-5. |
ANTHROPIC_TRIAGE_MODEL, ANTHROPIC_ASSISTANT_MODEL, ANTHROPIC_PLAN_MODEL, ANTHROPIC_ROUTE_MODEL, ANTHROPIC_FINISH_MODEL, ANTHROPIC_RECIPE_MODEL |
Each feature’s Claude model, as for Gemini below. The assistant falls back to the triage model. |
GEMINI_API_KEY |
Gemini: attention triage, the assistant, Autopilot’s placement, Auto-Done, recipe detection, Start Work, and voice without its own key. |
GEMINI_REFERER |
For a referrer-restricted key: the referrer it allows, as a full URL. |
GEMINI_API_BASE |
A fake Gemini for local checks. Leave it unset. |
GEMINI_TRIAGE_MODEL |
Triage’s model. Default gemini-3.6-flash, which every model below falls back to. |
GEMINI_ASSISTANT_MODEL |
The assistant’s model. |
GEMINI_PLAN_MODEL |
Autopilot placement’s model. |
GEMINI_ROUTE_MODEL |
Start Work’s team guess and title suggestion. |
GEMINI_FINISH_MODEL |
Auto-Done’s finish classifier. |
GEMINI_RECIPE_MODEL |
Recipe detection. |
AI_GATEWAY_API_KEY |
The Vercel AI Gateway: every model call with LLM_PROVIDER=gateway (voice too), and the fallback without an Anthropic or Gemini key. |
AI_GATEWAY_API_BASE |
A fake gateway for local checks. |
AI_GATEWAY_RECIPE_MODEL |
Recipe detection through the gateway. Default google/gemini-3.6-flash. |
AI_GATEWAY_TRIAGE_MODEL |
Triage and the drive answers through the gateway. Default google/gemini-3.6-flash. |
AI_GATEWAY_ASSISTANT_MODEL, AI_GATEWAY_FINISH_MODEL, AI_GATEWAY_PLAN_MODEL, AI_GATEWAY_ROUTE_MODEL |
The other features’ gateway models. Each defaults to google/ and the feature’s Gemini model. |
VOICE_PROVIDER |
gemini or vercel. Empty: follow the AI backend (gateway → vercel, direct → gemini; voice never runs on a machine, so machine → the first with a key). |
VOICE_TRANSPORT |
token (default) or relay (Node only). GEMINI_VOICE_TRANSPORT is the older name. |
GEMINI_VOICE_API_KEY |
A voice key without a website restriction. Default GEMINI_API_KEY. |
GEMINI_VOICE_MODEL |
Gemini’s voice model, for direct. Default gemini-3.8-live. |
LLM_VOICE_MODEL |
The gateway’s realtime voice model. Default google/gemini-3.8-live; an org can set its own. AI_GATEWAY_VOICE_MODEL is the older name. |
Integrations and push
| Variable | What it is |
|---|---|
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY |
Web Push. Without both, push is off. |
VAPID_SUBJECT |
The push contact, mailto:…. |
ASANA_CLIENT_ID, ASANA_CLIENT_SECRET, ASANA_REDIRECT_URI |
An Asana OAuth app. Without them, an org connects Asana with a personal access token. |
ASANA_OAUTH_SCOPES |
The app’s scopes, space-separated, for an app with granular scopes. |
Set by the platform
The server reads these to find its own address and limits. You don’t set them.
| Variable | Set by |
|---|---|
VERCEL, VERCEL_ENV, VERCEL_URL, VERCEL_BRANCH_URL, VERCEL_PROJECT_PRODUCTION_URL |
Vercel |
RENDER_EXTERNAL_URL |
Render |
RAILWAY_PUBLIC_DOMAIN |
Railway |
FLY_APP_NAME |
Fly.io |
PATH |
the system (andon-server up looks for tailscale on it) |
andon-server up
| Variable | What it is |
|---|---|
ANDON_UP_HOME |
The folder .andon goes in. Default: your home folder. |
ANDON_UP_PORT |
The port. Default 8787. |
ANDON_UP_TAILNET |
off: listen on 127.0.0.1 only, not on this machine’s Tailscale address too. |
ANDON_UP_BUNDLE |
Set by the desktop app: run its bundled server and board instead of a checkout’s. |
ANDON_UP_RESTART |
on: after Share over HTTPS on the board, the server runs andon up again, which restarts it on the HTTPS address. andon up sets it in the server’s environment; leave it unset on a server. Ignored on Vercel. |
The agent
| Variable | What it is |
|---|---|
ANDON_CONFIG_DIR |
The config folder. Default ~/.config/andon. |
ANDON_HOME |
Moves everything the agent writes under your home folder (tests and demos). |
ANDON_PROFILE |
Which agent on this machine a command is for, like --profile. |
ANDON_CREDENTIAL_BACKEND |
andon setup: where the sign-in is kept (keychain, secret-service or file). |
ANDON_HOOK_PORT |
andon setup: the hook server’s port. |
ANDON_NO_BROWSER |
andon setup: don’t open the browser. |
ANDON_NO_PROMPT |
Ask nothing, as if there were no terminal. |
ANDON_CAPTURE_TOKEN |
The capture token andon add sends. Wins over the saved one. |
ANDON_CAPTURE_URL |
Send andon add to this capture endpoint instead of the enrolled board’s. |
ANDON_API_TOKEN |
A personal API token for the card commands. Wins over the saved one. |
ANDON_UPDATE_KEY |
The release key updates are checked against, instead of the one the installer pinned. |
ANDON_CHROME |
The headless Chrome or Chromium for preview frames, when bins.chrome isn’t set. |
CLAUDE_CONFIG_DIR |
Claude Code’s folder, where the use-andon skill goes. |
CODEX_HOME |
Your Codex folder: where the agent finds your Codex login, and where Codex reads the shared skill. |
GEMINI_API_KEY, GOOGLE_GENAI_USE_GCA, GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GEMINI_BASE_URL, CLOUD_SHELL, GEMINI_CLI_USE_COMPUTE_ADC |
Gemini CLI’s own sign-in variables. When the agent’s environment has one, a Gemini CLI account with no saved login shows as unknown rather than signed out, since a run may still sign in with it. |
COPILOT_HOME |
GitHub Copilot’s folder, for the skill. |
HERMES_HOME |
Hermes Agent’s folder, for the skill. |
XDG_DATA_HOME |
Where the agent keeps the skill’s own copy. Default ~/.local/share. |
XDG_STATE_HOME |
Linux: where the service’s logs go. Default ~/.local/state. |
XDG_CONFIG_HOME |
Linux: where the systemd user unit goes. Default ~/.config. |
HOME, USER, LOGNAME, PATH |
Your home folder, user name and program path. |
DISPLAY, WAYLAND_DISPLAY, DBUS_SESSION_BUS_ADDRESS |
Linux: whether there is a desktop (for linger and the Secret Service). |
The agent sets these for a run’s processes. Don’t set them yourself:
| Variable | What it is |
|---|---|
KANBAN_RUN_ID |
The run the MCP server and hooks report for. |
ANDON_THREAD_ID |
The chat thread, when the MCP server serves the board’s chat. |
ANDON_THREAD_KIND |
coordinator when that thread is a coordinated workstream’s (the MCP server then lists the coord_* tools instead of the chat’s), planning when it is a planning session’s (the planning session tools). |
ANDON_HOOK_URL, ANDON_HOOK_TOKEN |
Where the hooks and the MCP server reach the agent, and the secret they send. |
GEMINI_CLI_HOME |
Gemini CLI’s home: Andon gives each account its own, and never touches ~/.gemini. |
The docs site
apps/docs reads these at build time. All are public: they end up in the pages.
| Variable | What it is |
|---|---|
PUBLIC_DOCS_GITHUB_URL |
The repository’s GitHub address. Set, the header shows a GitHub link and each page an Edit this page link. Unset, neither shows. |
PUBLIC_DOCS_BOARD_URL |
A board address for Open your board in the header and the phone menu. Unset, the button doesn’t show. |
PUBLIC_DOCS_SITE_URL |
The docs site’s own address, such as https://docs.example.com. Set, /llms.txt, /llms-full.txt, the pages’ Markdown twins and the changelog’s feed (/changelog/rss.xml) link pages by full address. Unset, they link by path from the site’s root. |
