Skip to content
AndonDocs
GitHub
Look something up

The andon-server command

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

andon-server runs the portable server: the board, its API and its database migrations, on any Node host with Postgres. It reads its settings from the environment (environment variables).

From a checkout, run it as node apps/server/src/cli.ts <command>, or through the pnpm scripts below. Every command and flag is checked against the code by a test (apps/server/test/reference-docs.test.ts).

Command What it does pnpm script
andon-server start Apply pending migrations, then serve the API (and the built board, when there is one) on PORT (default 8787). pnpm dev:server
andon-server migrate Apply db/migrations to DATABASE_URL_DIRECT (or DATABASE_URL), then sync the AI switches with the environment.
andon-server up Andon on this machine in one command: Postgres, the server with the board on port 8787, and this machine’s agent, with the data in ~/.andon. pnpm andon:up
andon-server db start|stop|reset|status|url This checkout’s own local Postgres, for development. pnpm db:local …
andon-server rotate-secrets Re-encrypt the stored secrets under the current ANDON_SECRET_KEY.

andon-server up

The first run opens /setup in the browser, waits for you to make the owner account, then enrolls this machine’s agent into the new org. Later runs start whatever isn’t running. On Windows it starts Postgres and the server but not the agent.

Flag What it does
--stop Stop the agent, the server and Postgres. The data stays.
--reset Stop, then start again with an empty database. The old files and the agent’s config are set aside, not deleted.
--no-browser Don’t open the browser.
--url <address> Serve it as this address, such as a reverse proxy’s https:// name. Later runs keep it; --url auto goes back to the address below.

The server’s own address (ANDON_URL) is the one --url set. Without one, it’s this machine’s HTTPS address on the tailnet once tailscale serve shares it, else http://localhost:8787. Passkeys and the links the server builds use it. When the server runs on another address, andon up restarts it. localhost keeps working beside it.

ANDON_UP_HOME moves ~/.andon, and ANDON_UP_PORT changes the port.

andon-server db

Subcommand What it does
db start Start this checkout’s Postgres (in .andon/pg), create the andon database, migrate it, and print its DATABASE_URL.
db url The same, printing only the DATABASE_URL.
db reset Drop and recreate the andon database, then migrate it.
db status Whether it’s running, and on which port.
db stop Stop it.

andon-server rotate-secrets

To change ANDON_SECRET_KEY:

  1. Set the new key as ANDON_SECRET_KEY and the old one as ANDON_SECRET_KEY_PREVIOUS (comma-separate several).
  2. Run andon-server rotate-secrets.
  3. When it says every secret is under ANDON_SECRET_KEY, remove ANDON_SECRET_KEY_PREVIOUS.

A secret that neither key decrypts is left alone and named, and the command exits 1: add its key, or set that secret again.