# Environment variables

The server takes all its settings from the environment. The agent takes almost none: its settings are in
[its config file](https://andon-docs.pages.dev/reference/agent-config.md), 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](https://andon-docs.pages.dev/reference/server-cli.md#andon-server-rotate-secrets). |
| `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](https://andon-docs.pages.dev/guide/needs-you.md#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](https://andon-docs.pages.dev/machines/ai-backends.md)). 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. |
