Get started with Beacon locally
Use this tutorial to run Beacon locally for the first time. Beacon provides the management API and browser interface, Drift stores the authoritative data, and Compactor executes redirects. You need Drift for this tutorial; you can add Compactor later when you want to test redirect traffic.
Before you begin
You need Node.js 22 or newer and a reachable Drift tenant with a read/write key. If you do not have those yet, follow Drift's getting-started tutorial and tenant and key tutorial.
From the Beacon repository root, install dependencies and create your local configuration:
cd /path/to/beacon
npm ci
cp .env.example .env
Generate all four Beacon credentials in a POSIX-compatible shell. This exports them into the current terminal and prints them; copy the printed values into .env.
. scripts/generate-beacon-secrets.sh
Then edit .env: set DRIFT_URL to the Drift base URL, set DRIFT_API_KEY to the tenant key, and paste all four generated values. Keep BEACON_BROWSER_ORIGIN=http://localhost:5173 for the local web application; it authorizes its requests to the API at port 3100. See the environment-variable reference for every variable, default, constraint, and rotation effect.
Start Beacon
Beacon reads the process environment; it does not load .env itself. In one terminal, export the file and start the API:
set -a
. ./.env
set +a
npm run dev
This sequence makes .env values win over values that were already exported. To override one setting for this run, export it after sourcing .env; the environment reference covers local and Compose precedence.
In another terminal, start the browser application:
npm run dev:web
Open http://localhost:5173. Complete first-run setup with the deployment-provided setup token, a lowercase-compatible username, and a password of at least 12 characters.
Guaranteed: the development server forwards /api/* and /integrations/* to Fastify at http://127.0.0.1:3100. It does not place Drift credentials or Compactor bearer tokens in browser code.
Verify the result
Confirm Fastify is reachable:
curl --fail http://127.0.0.1:3100/health
Then sign in at http://localhost:5173, create a redirect with a new destination, and confirm it appears in search.
What to do next
Use the self-hosting guide to run the complete Beacon, Drift, and Compactor stack. Compactor's HTTP-adapter tutorial explains the runtime side of Beacon's resolver and event-sink connection; Beacon's API reference defines the matching endpoints. Do not reuse development secrets in a deployment.