Run Briefs locally

Get the API and this docs site running in a few minutes. Uses npm workspaces — install with npm ci, never ad-hoc npm install in production pipelines.

Prerequisites

Node.js 22+
Docker (for Postgres)
Repo cloned from holmplanet/briefs

Install and start

Terminal

cd briefs
npm ci
cp .env.example .env
npm run db:up
npm run dev:system    # API — default http://localhost:8001
npm run dev:daily     # Briefs Daily — http://localhost:3000
npm run dev:docs      # SDK docs — http://localhost:3001

Environment

API config lives in .env at the repo root. Web clients use .env.local in their package directory:

client/web/daily/.env.local

NEXT_PUBLIC_API_URL=http://localhost:8001
NEXT_PUBLIC_USER_ID=demo
NEXT_PUBLIC_DOCS_URL=http://localhost:3001

The API defaults to port 8001 so it does not conflict with the Brief MCP server on 8000. Override with APP_PORT in the repo root .env and match NEXT_PUBLIC_API_URL in your web client.

Verify the API

From the repo root, run the CLI smoke test (starts against your local API on port 8001):

Terminal

npm run briefs:smoke

Or verify individual endpoints with curl:

Health

curl http://localhost:8001/health

List items

curl -H "X-Briefs-User-Id: demo" \
  http://localhost:8001/api/v1/items

Create an item

curl -H "X-Briefs-User-Id: demo" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ship items UI","kind":"task"}' \
  http://localhost:8001/api/v1/items

Resolve your actor

curl -H "X-Briefs-User-Id: demo" \
  http://localhost:8001/api/v1/actors/me

Briefs Daily

Browse Briefs Daily for the reference web client and local setup.