Skip to main content

Run Costpilot

Costpilot is one service: the API serves the built dashboard, prices and stores telemetry in SQLite, and needs nothing but a volume. Pick whichever way to run it suits you right now. You can switch later; the data lives in one SQLite file.

Option A: locally on your machine​

Best for a first look and for development. Node 20 or newer is required.

git clone https://github.com/getcostpilot/core.git costpilot
cd costpilot
npm install
DEMO_MODE=1 npm run dev     # API on :8787, dashboard on :5173

Open http://localhost:5173. The dashboard talks to the API through the Vite dev proxy, so there is nothing else to configure. DEMO_MODE=1 makes the server seed the demo dataset into the empty database (apps/api/ai-cost.db) and turns accounts off, so no sign-in is needed yet. Without the flag the first start prints a setup code instead, see below.

npm run seed writes the same dataset without starting the server; npm run seed -- --force wipes the database and seeds again.

Option B: Railway, one click​

Best for a team instance or a public demo.

Deploy on Railway

The template creates one service built from the API Dockerfile, a volume mounted at /data, and sets DEMO_MODE=1. Click, confirm, and Railway builds and starts a demo instance. Add a custom domain under Settings → Networking; Railway shows the CNAME target for your DNS provider.

For a manual Railway setup, Docker on any host, or Fly.io see the deployment guide.

Option C: Docker​

docker build -f apps/api/Dockerfile -t costpilot .
docker run -p 8080:8080 -v costpilot-data:/data -e DEMO_MODE=1 costpilot

Open http://localhost:8080.

Look around the demo data​

With DEMO_MODE=1 the dashboard shows a realistic dataset of about eleven weeks: six squads, 36 engineers, roughly 23k USD of AI spend. The dataset always ends today; it is reseeded on the first request of each UTC day and after an upgrade that changes the demo dataset. Use it to get a feel for the dashboard before your own data arrives:

  • The hero band at the top shows spend, issues touched and average cost per issue for the selected date range (turns and average cost per turn once the scope is a single issue), with deltas against the previous period and the cost-per-day trend.
  • The dimension tiles break cost down by project, issue, actor, provider, model, source and repository. Click a value to drill down; the breadcrumb takes you back.
  • The Analysis tab compares issues by cost, turns or cost per turn and lets you compare two groups.
  • Tool usage and budget alerts sit below the overview.

Demo mode is flagged in the UI, turns accounts off, hides the Admin Area and makes branding read-only. The daily reseed wipes the whole database, so turn it off before real data arrives, see See your first session.

Set up a team instance before developers connect​

Outside demo mode the dashboard requires a sign-in. On first start the server log prints a one-time setup code:

Auth: no account yet - open the dashboard and enter setup code 1a2b3c...

Open the dashboard, enter the code and create the first admin. For automated deployments set COSTPILOT_ADMIN_EMAIL and COSTPILOT_ADMIN_PASSWORD instead. Invite the rest of the team under Admin → Users.

Ingestion is separate from accounts: the agent has no interactive login, so /v1/* is protected by a bearer token:

COSTPILOT_INGEST_TOKEN=<secret>

That is the value developers pass to the agent as --token. Set it before you hand out the URL. Details in Secure your instance.

Next: Connect your tools.