Deploy Andon
Deploy Andon when a team shares one board, or when the board has to stay up while your computer sleeps. An instance is one server, which also serves the board, and one Postgres 15 or newer from any provider. The code is the same on every host.
Everyone on a shared board adds their own machines, and each person’s cards run only on their own machines. The server runs no cards itself.
To try Andon on your own computer instead, use the desktop app, or
pnpm andon:up from a clone.
Choose a host
Andon runs in one of two shapes. Pick the one that fits how you want to run it, then a recipe below.
| One box: a container or a VPS | Vercel and a hosted Postgres | |
|---|---|---|
| What runs | one long-lived server process with the board inside, next to Postgres | the board on Vercel’s CDN, /api/* as one function, Postgres from the Marketplace |
| You look after | the box: its updates, TLS (Caddy in the Compose recipe), disk and backups | nothing but the Vercel project’s and the database’s settings |
| Scheduled work | every 15 seconds, on the server’s own timer | when Vercel Cron calls (daily by default; every minute on Pro with ANDON_CRON), and when a machine’s heartbeat finds work due |
| Live updates | no platform time limit: a stream ends only when its sign-in token does, and reconnects | streams close before the function’s time limit (300 s by default) and reconnect by themselves |
| Voice in the assistant | short-lived tokens, or VOICE_TRANSPORT=relay to keep every call on the server |
short-lived tokens only: a function can’t hold the relay’s socket |
| Files | the same volume, or S3 | Vercel Blob, or S3 |
| Cost | the box: a small VPS is enough for a team | Hobby is for personal trials; teams use Pro |
Choose one box when you want everything on a machine you control, on a tailnet or behind your own domain, with
no platform limits. Choose Vercel when you’d rather run no server at all and a team’s board can live on Pro.
Either way you can move later: the database and the files are the whole instance, with ANDON_SECRET_KEY.
Pick a recipe
| Recipe | How | Database | Files | Guide |
|---|---|---|---|---|
| Vercel + Neon | Deploy button | Neon, from the Marketplace | Vercel Blob | deploy/vercel |
| Vercel + Supabase | Deploy button | Supabase, from the Marketplace | Vercel Blob, or Supabase Storage over S3 | deploy/vercel |
| Railway | Deploy from GitHub | Railway Postgres | a volume, or S3 | deploy/railway |
| Render | Blueprint (render.yaml) |
Render Postgres | a disk, or S3 | deploy/render |
| Fly.io, one machine | fly launch |
built in, on the volume | the same volume | deploy/fly |
| Fly.io | fly launch |
Fly Postgres, or any | a volume, or S3 | deploy/fly |
| A VPS | Docker Compose with Caddy | bundled postgres:17 |
a volume | below |
| Docker Compose | docker compose up |
bundled postgres:17, or any |
a volume, or S3 | deploy/compose |
| Docker, one container | docker run |
built in, on the volume | the same volume | below |
The steps every recipe shares
- Make a key. Run
openssl rand -base64 32and set the result asANDON_SECRET_KEY. It’s the only secret you provide: sign-in, the encryption of stored secrets and signed file links are all derived from it. Keep it with your backups. Without it, a restored database can’t read its own stored secrets. - Deploy with that key and a database URL. Migrations run by themselves: in the production build on Vercel, and when the server starts everywhere else.
- Open
https://<your host>/setupstraight away, with the setup token. The server prints it in its log when it starts (setup: open https://<your host>/setup#token=…: open that link, or paste the token on the page), or set your own asANDON_SETUP_TOKEN. Whoever has it creates the owner, who is the instance’s admin, and the first org. It works once, on a fresh instance. After that it stays closed, even if every org is later deleted. - Add machines. On each machine that should run cards, run
curl -fsSL https://<your host>/install.sh | sh, then approve it in the browser. Settings → Machines → Add machine shows the same line. - Invite people from the board.
The use-andon skill, which lets coding agents outside a run use Andon, comes with the agent, not the server. Each
machine gets it when you add the machine, whichever host you deploy on, Docker included.
Run the image yourself
The Dockerfile at the repository’s root builds the server with the built board inside, for linux/amd64 and
linux/arm64. The Compose, Railway, Render and Fly recipes build it themselves. The image:
- migrates the database when it starts
- serves the API and the board on
PORT(8787) - keeps files in
/data/storage, unlessS3_BUCKETis set - answers
GET /api/health
docker build -t andon-server .docker run -d --name andon -p 8787:8787 -v andon-data:/data \ -e ANDON_SECRET_KEY=<your key> \ -e DATABASE_URL=postgres://<user>:<password>@<host>:5432/andon \ -e ANDON_URL=https://andon.example.com \ andon-serverPut a TLS proxy in front of it for a public address, and set ANDON_IP_HEADERS to the header that proxy sets with
the client’s address (x-forwarded-for for Caddy), so sign-in rate limits see real clients.
Only a v* release tag publishes a prebuilt image, to ghcr.io/psci-labs/andon-server, tagged with its version and
latest. If there’s no release yet, build the image as above.
One container with its own database
The single target is the same image with PostgreSQL 17 inside it. The database lives in /data/pg and the files in
/data/storage, on one volume. Use it on any host that gives you one container and one volume. The Fly one-machine
recipe uses it too.
-
Build it:
shell docker build --target single -t andon-single . -
Run it, with no
DATABASE_URL:shell docker run -d --name andon --restart unless-stopped --stop-timeout 60 \-p 8787:8787 -v andon-data:/data \-e ANDON_SECRET_KEY=<your key> -e ANDON_URL=https://andon.example.com \andon-single -
Open
/setup, with the setup token fromdocker logs andon, and carry on with the shared steps.
At first start the container creates the database on the volume, with a generated password kept in
/data/.andon-db-password. Postgres listens inside the container only. On a stop, the server stops first (15 seconds
at most), then Postgres. --stop-timeout 60 gives both time to stop cleanly: Docker’s default of 10 seconds cuts
Postgres off.
If you set DATABASE_URL (or any other database URL the server reads) later, the same image leaves its own database
off and uses yours.
To take a dump you can keep elsewhere:
docker exec andon setpriv --reuid=postgres --regid=postgres --init-groups \ pg_dump -h /run/postgresql -Fc -f /tmp/andon.dump andondocker cp andon:/tmp/andon.dump .bash scripts/fly-single-smoke.sh builds this image, runs it on a fresh volume, creates the owner, restarts it and
checks the data is still there.
On a fresh VPS
A single box with a public address, such as an Ubuntu or Debian VPS. This is the Compose recipe with its bundled database and Caddy for TLS.
-
Point a domain at it. Make an
A(andAAAA) record forandon.example.comwith the VPS’s address, and allow ports 22, 80 and 443 in its firewall. Caddy needs 80 and 443 to get a Let’s Encrypt certificate. -
Install Docker and git, as a user in the
dockergroup:shell sudo apt-get update && sudo apt-get install -y gitcurl -fsSL https://get.docker.com | sudo shsudo usermod -aG docker "$USER" && newgrp docker -
Configure the Compose recipe:
shell git clone https://github.com/psci-labs/andon && cd andon/deploy/composecp .env.example .envIn
.env, setANDON_HOST=andon.example.com,ANDON_SECRET_KEYtoopenssl rand -base64 32, andPOSTGRES_PASSWORDtoopenssl rand -hex 24. -
Start it:
docker compose --profile db up -d --build. The first build takes a few minutes. The containers start again by themselves after a reboot. -
Check it:
curl -fs https://andon.example.com/api/healthanswers{"ok":true,…}. -
Set up: open
https://andon.example.com/setupwith the token fromdocker compose logs server | grep 'setup token', then carry on with the shared steps.
Then send email with SMTP_URL in .env (and docker compose up -d), and back up the two
volumes with the key. To keep the VPS off the public internet, put it on your tailnet instead:
On your tailnet.
Run it from a clone
From a clone, with Node 22 and pnpm 10 and no Docker, andon up runs Postgres, the server with the board on
http://localhost:8787, and this machine’s agent. The data lives in ~/.andon.
pnpm installpnpm andon:up # startpnpm andon:up --stop # stop all three; the data stayspnpm andon:up --reset # start again with an empty databaseThe first run builds the board, opens /setup in your browser and waits there. Once you’ve created the owner, it
enrols this machine’s agent into the new org and starts it. On this computer /setup needs no setup token;
from another device, use the one printed in the server’s log. Emails, such as sign-in codes and invites, go to
~/.andon/mail.log, and none is sent unless SMTP_URL is set in the shell that starts it. On Windows it runs Postgres, the server and the board, but no agent: cards run on a Mac or Linux
machine, or in WSL2 on the same PC (Windows machines).
andon up starts its three processes and exits; nothing supervises them. After a crash, a log-out or a reboot, run
pnpm andon:up again. For a board that stays up by itself, use one of the recipes above.
| Variable | What it does |
|---|---|
ANDON_UP_HOME |
The folder that holds .andon, instead of your home folder. |
ANDON_UP_PORT |
The port, instead of 8787. |
ANDON_UP_TAILNET=off |
Keep it on localhost, even when the machine is on a Tailscale network. |
On a tailnet, the board’s Share over HTTPS (Settings → Machines) gives it https://<machine>.<tailnet>.ts.net.
andon up then restarts the server on that address. Passkeys work there and on localhost, and the links the server
builds itself use the HTTPS address. A link the server hands back to your browser is still built on the address
you’re using. Behind your own HTTPS proxy, name its address instead: pnpm andon:up --url https://andon.example.com.
The proxy must pass its own host on, as Host or X-Forwarded-Host, or passkeys may be offered for localhost.
Later runs keep that address. --url auto goes back to the tailnet address.
To move it to an always-on box later, such as a NAS or a home server on your tailnet, see
Moving an andon up install.
Host the board somewhere else
The board is a static build. To serve it from its own static host, build it with the server’s address and send every
unknown path to index.html:
VITE_ANDON_URL=https://api.example.com pnpm --filter @andon/board build # into apps/board/distThen set ANDON_BOARD_ORIGINS=https://board.example.com on the server. Cache assets/ for a year and everything else
with no-cache. The repository’s vercel.ts and deploy/compose/Caddyfile show the rules.
Settings
The server reads everything from its environment. The repository’s .env.example lists every variable. The ones most
deployments set:
| Variable | What it does |
|---|---|
ANDON_URL |
Where Andon is reached. Defaults to the platform’s own address on Vercel, Render, Railway and Fly, else http://localhost:8787. |
DATABASE_URL, DATABASE_URL_DIRECT |
The database. Behind a transaction pooler, DATABASE_URL_DIRECT is the direct or session-mode URL, for migrations and live updates. |
SMTP_URL, MAIL_FROM |
Email for invites and sign-in codes. Without them, codes go to the server’s log. |
ALLOW_SIGNUPS |
Let anyone sign up. Off by default, so people join by invite. Either way they join this instance’s org: an instance holds one org, and another org is another instance. |
TURNSTILE_SECRET_KEY |
Bot protection: signing up, a password sign-in and every emailed code need a passed Cloudflare Turnstile check. Set it only with a board built with the matching VITE_TURNSTILE_SITE_KEY, as Vercel’s build does from the project’s settings. The Docker image’s board is built without one, so leave it unset there, or every password and email-code sign-in fails. |
S3_*, ANDON_STORAGE |
Files on S3, R2, B2, MinIO or Supabase Storage, instead of the disk or Vercel Blob. |
GITHUB_CLIENT_ID, GOOGLE_CLIENT_ID, APPLE_CLIENT_ID and their secrets |
Sign-in with GitHub, Google or Apple. |
GEMINI_API_KEY, AI_GATEWAY_API_KEY |
Model calls: the assistant, attention triage, recipe detection, Autopilot, Start work, Auto-Done and voice. LLM_PROVIDER picks the default backend. An org can bring its own keys and choose its backend under Settings → Connections → Advanced (AI backends). |
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY |
Web Push notifications. |
Update
Redeploy the new version. On Docker, build or pull the new image and create the container again from it, because
docker restart keeps the old image. Compose does both with git pull && docker compose --profile db up -d --build.
Migrations apply by themselves, in order, under a lock, each in its own transaction. Agents update themselves from the
board.
Back up
Back up the database and the files, and keep ANDON_SECRET_KEY with them:
- Docker Compose, and a VPS: the
pgdataandstoragevolumes, or your own database. - Fly.io, one machine, and Docker, one container: the one volume, or a
pg_dumpas shown in each section. - Vercel, Railway and Render: your database provider’s backups, and the Blob store, volume, disk or S3 bucket.
Change the secret key
Change ANDON_SECRET_KEY if it may have leaked. Sign-in sessions and signed file links are derived from the key, so
everyone signs in again afterwards.
-
Make a new key:
openssl rand -base64 32. -
Set
ANDON_SECRET_KEYto the new key andANDON_SECRET_KEY_PREVIOUSto the old one, then redeploy. For several old keys, separate them with commas. On Docker, create the container again with the new variables (docker compose up -d, ordocker stop andon && docker rm andonand the samedocker run), becausedocker restartkeeps the old ones. -
Run
rotate-secretswith the server’s environment. Pick the line for your host:Host Command Docker Compose docker compose exec server node apps/server/src/cli.ts rotate-secretsDocker, plain image docker exec andon node apps/server/src/cli.ts rotate-secretsDocker, one container docker exec andon sh -c 'DATABASE_URL="postgres://andon_owner:$(cat /data/.andon-db-password)@127.0.0.1:5432/andon" node apps/server/src/cli.ts rotate-secrets'Fly.io see below the table Vercel, Railway, Render from a clone after pnpm install:ANDON_SECRET_KEY=<new> ANDON_SECRET_KEY_PREVIOUS=<old> DATABASE_URL=<the direct URL> node apps/server/src/cli.ts rotate-secretsOn Fly.io, run
fly ssh console, then in that shell:shell cd /appnode apps/server/src/cli.ts rotate-secrets # with a separate databaseDATABASE_URL="postgres://andon_owner:$(cat /data/.andon-db-password)@127.0.0.1:5432/andon" \node apps/server/src/cli.ts rotate-secrets # one machineIf that shell lacks the server’s variables, set them on the command line as in the Vercel row.
It prints how many secrets it re-encrypted. A secret that neither key opens is left alone and named: add its key to
ANDON_SECRET_KEY_PREVIOUS, or set that secret again on the board. -
When it says
ANDON_SECRET_KEY_PREVIOUS can go, remove that variable and redeploy again, the same way.
Sign the agent builds you publish
The board serves the agent that machines install and update from. Sign it, so a machine can tell an update came from you:
- Make an Ed25519 private key in PKCS#8 form and keep it offline.
- Give it to the board’s build only, base64url-encoded, as
ANDON_UPDATE_SIGNING_KEY. The build signsagent/latest.jsonwith it. - The board’s install.sh then pins the matching public key by default. To give a machine the key through a channel
you trust, separate from the board, install with
curl -fsSL https://<your host>/install.sh | sh -s -- --update-key <key>, or setANDON_UPDATE_KEY.
A board you build without a key serves unsigned agent builds. Its install.sh pins Andon’s own release key instead, and its machines update from Andon’s official releases. Agent updates explains what a machine checks.
