Skip to content
AndonDocs
GitHub
Look something up

Environment variables

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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.

On this page
View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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.