Skip to content
AndonDocs
GitHub
Run machines and deploy / Deploy an instance and the desktop app

Deploy Andon

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

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

  1. Make a key. Run openssl rand -base64 32 and set the result as ANDON_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.
  2. 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.
  3. Open https://<your host>/setup straight 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 as ANDON_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.
  4. 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.
  5. 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, unless S3_BUCKET is set
  • answers GET /api/health
shell
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-server

Put 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.

  1. Build it:

    shell
    docker build --target single -t andon-single .
  2. 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
  3. Open /setup, with the setup token from docker 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:

shell
docker exec andon setpriv --reuid=postgres --regid=postgres --init-groups \
pg_dump -h /run/postgresql -Fc -f /tmp/andon.dump andon
docker 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.

  1. Point a domain at it. Make an A (and AAAA) record for andon.example.com with 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.

  2. Install Docker and git, as a user in the docker group:

    shell
    sudo apt-get update && sudo apt-get install -y git
    curl -fsSL https://get.docker.com | sudo sh
    sudo usermod -aG docker "$USER" && newgrp docker
  3. Configure the Compose recipe:

    shell
    git clone https://github.com/psci-labs/andon && cd andon/deploy/compose
    cp .env.example .env

    In .env, set ANDON_HOST=andon.example.com, ANDON_SECRET_KEY to openssl rand -base64 32, and POSTGRES_PASSWORD to openssl rand -hex 24.

  4. 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.

  5. Check it: curl -fs https://andon.example.com/api/health answers {"ok":true,…}.

  6. Set up: open https://andon.example.com/setup with the token from docker 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.

shell
pnpm install
pnpm andon:up # start
pnpm andon:up --stop # stop all three; the data stays
pnpm andon:up --reset # start again with an empty database

The 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:

shell
VITE_ANDON_URL=https://api.example.com pnpm --filter @andon/board build # into apps/board/dist

Then 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 pgdata and storage volumes, or your own database.
  • Fly.io, one machine, and Docker, one container: the one volume, or a pg_dump as 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.

  1. Make a new key: openssl rand -base64 32.

  2. Set ANDON_SECRET_KEY to the new key and ANDON_SECRET_KEY_PREVIOUS to 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, or docker stop andon && docker rm andon and the same docker run), because docker restart keeps the old ones.

  3. Run rotate-secrets with 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-secrets
    Docker, plain image docker exec andon node apps/server/src/cli.ts rotate-secrets
    Docker, 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-secrets

    On Fly.io, run fly ssh console, then in that shell:

    shell
    cd /app
    node apps/server/src/cli.ts rotate-secrets # with a separate database
    DATABASE_URL="postgres://andon_owner:$(cat /data/.andon-db-password)@127.0.0.1:5432/andon" \
    node apps/server/src/cli.ts rotate-secrets # one machine

    If 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.

  4. 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:

  1. Make an Ed25519 private key in PKCS#8 form and keep it offline.
  2. Give it to the board’s build only, base64url-encoded, as ANDON_UPDATE_SIGNING_KEY. The build signs agent/latest.json with it.
  3. 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 set ANDON_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.