Self-hosting

You do not need this page to use Tracemason: the hosted service at app.tracemason.com needs only an account and npx @tracemason/cli init (see Getting started). This page is for running Tracemason yourself, for development or on your own infrastructure.

Run it locally

You need Node.js 22+, pnpm and Docker.

git clone <this repository> tracemason && cd tracemason
cp .env.example .env
# set BETTER_AUTH_SECRET and GITHUB_WEBHOOK_SECRET in .env (openssl rand -base64 32)
docker compose up -d          # PostgreSQL on 5433, Redis on 6380
pnpm install
pnpm build                    # builds packages, API and collector
pnpm dev                      # API on http://localhost:4100, web on http://localhost:3100

Migrations run automatically when the API starts.

Look around with demo data

With SEED_DEMO=1 (the default in .env.example) the API creates a demo workspace on first boot. On the sign-in page choose Open the demo workspace, or sign in as [email protected] / demo-password.

Demo events are synthetic and deterministic, but they are not inserted directly: the seed script sends them through the real ingestion pipeline, policy engine and correlation engine. Every screen in the demo workspace carries a "Demo data" banner. The hosted service has no demo workspace.

Point the collector at your server

Pass --endpoint so the collector reports to your server instead of the hosted service:

npx @tracemason/cli init --endpoint https://tracemason.your-company.com

From a checkout, the same collector is pnpm tracemason init --endpoint http://localhost:3100. The endpoint must be https, except for localhost.

Production settings

Set NODE_ENV=production, SEED_DEMO=0, a generated BETTER_AUTH_SECRET and GITHUB_WEBHOOK_SECRET, DATABASE_URL, REDIS_URL, and WEB_ORIGIN to the public https address people sign in at. Put TLS in front of the web app; the browser and the collector only ever talk to that address, which proxies /api/* to the API.