Dispatcher

This repository is the source of the Dispatcher template on Railway.

Go API + React Router SPA, shipped as a single binary.

• main.go — wiring: env, database, routes, server.
• handlers.go — /api/* handlers.
• db.go — GORM models and connection.
• spa.go — serves the built frontend (embedded via go:embed), with an index.html fallback for client-side routes.
• web/ — React Router v7 app in SPA mode (Vite is its build tool; it outputs static files to web/build/client).

Development

Two terminals:

make dev-api   # Go API on http://localhost:8090
make dev-web   # frontend on http://localhost:5173, proxies /api to the Go server

Work against http://localhost:5173 — you get Vite HMR, and API calls hit Go.

Production

make build     # npm run build, then go build (frontend embedded)
./dispatcher   # serves everything on :8090 (override with PORT)

Note: go build embeds web/build/client, so the frontend must be built first — make build handles the order.

Database

GORM with DuckDB (via github.com/vogo/duckdb/v2). Data lives in dispatcher.duckdb next to the binary (override with DB_PATH); db.go holds the models and connection, and AutoMigrate runs on startup. Building needs CGO (DuckDB links a C library) — already the Go default.

Sessions

The auth cookie carries the whole Railway OAuth grant — access token, refresh token, expiry — sealed with AES-GCM under the OAuth client secret. There is no session table: Railway stays the only authority on who you are.

A Railway access token lasts about an hour, which is how long a login used to last. requireAuth now refreshes the grant when the access token is spent, re-seals the cookie, and carries on, so a login lives for as long as Railway honours the refresh token. Parallel requests that arrive on an expired token share a single refresh. Every request is still validated against Railway, so losing workspace access ends the session at once, and the refreshed token is also written to the stored workspace credentials that background jobs use.

The cookie is encrypted rather than signed so a leaked cookie cannot be replayed against Railway's own API, and it is HttpOnly, SameSite=Lax, and Secure whenever CALLBACK_URL is HTTPS. Its lifetime is 400 days, the ceiling browsers accept; dispatcherctl stores the same value and adopts the renewed session whenever Dispatcher rotates it. Logging out drops the cookie, and re-registering the OAuth client invalidates every session, since the client secret is the encryption key.

Dispatcher registers its own OAuth client with Railway on first login. If Railway later revokes it (invalid_client on login), Dispatcher drops it and sends the browser back through login with a freshly registered one. Like any new client, that signs everyone out (CLI included), and background jobs resume after the first login.

Notifications

Notification targets send payout requests, template health drops, and weekly template summaries to Discord, Slack, ntfy, or a custom HTTP webhook. Targets use editable Go text/templates and can be tested before they are enabled.

Background collection, auto-withdraw, weekly summaries, and notification delivery assume the app runs as a single process. Running multiple replicas can duplicate cron work and notifications.

CLI

dispatcherctl is a small, standalone HTTP client intended for agents and scripts. It queries a running Dispatcher instance, never its DuckDB file or Railway directly. Authenticated commands use the same Railway OAuth flow and session as the browser app; there are no separate API tokens. The health check remains public just like /api/health.

Install the latest CLI release on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/ThallesP/dispatcher/main/install.sh | sh

The installer verifies the release checksum and installs to /usr/local/bin when it is writable, otherwise to ~/.local/bin. Set DISPATCHER_INSTALL_DIR to choose another directory, or DISPATCHER_VERSION=v0.1.0 to install a specific release.

You can also build or install from source:

make build-cli
# Or: make install-cli

./dispatcherctl login       # asks for the Dispatcher URL, then opens Railway OAuth
./dispatcherctl whoami

./dispatcherctl summary
./dispatcherctl templates
./dispatcherctl payouts --days 90
./dispatcherctl projects umami-analytics --days 90   # a template's id or code
./dispatcherctl notifications
./dispatcherctl withdraw-settings
./dispatcherctl withdraw-accounts

The first login asks for the Dispatcher instance URL and saves it after OAuth succeeds. Later commands and logins reuse that URL automatically. --url and DISPATCHER_URL override the saved instance; a successful login through an override makes it the new default.

During login Dispatcher creates a short-lived pending login and returns a Railway authorization URL. The CLI opens that URL (or prints it in a headless environment) and polls Dispatcher while the browser completes the existing OAuth callback. Browser and CLI login share the same Railway authorization URL builder, code exchange, workspace-access check, saved credentials, and requireAuth cookie middleware. The only CLI-specific part is how the completed session reaches the terminal. Sessions renew themselves, so a CLI login lasts until Railway revokes the grant. That result is bound to a verifier held only by the CLI, so the browser never receives the Railway session itself. This also works when the CLI and browser are on different machines. Sessions are stored with owner-only permissions in the operating system's user config directory. Use dispatcherctl logout to remove the session for an instance.

This is the beginning of the README. Read the rest at the original. Read the full README ↗