Quickstart

specd is local-first and pre-1.0: you run it on your own machine, against your own Postgres, with your own model credential. There is no hosted service to sign up for.

Prerequisites

The one-command path

git clone https://github.com/unitypark/specd.git && cd specd
pnpm install
pnpm demo

pnpm demo writes a .env if there is not one, builds the workspace packages, starts Postgres and waits for it to actually accept connections, applies migrations, seeds a project with a fixture repository already connected, and starts both dev servers — printing the URL and a login. Each step announces itself, so a failure names the step instead of arriving as a stack trace three steps later.

The same thing by hand

If you would rather see each step, this is exactly what pnpm demo automates.

1. Clone and configure

   cp .env.example .env. The file only has to exist — the dev defaults work as-is, and nothing needs sourcing into your shell: the API, the migration runner and Next.js each load the repo-root .env themselves. Every value you would change for a real environment is commented with what it does and how to generate it.

2. Install and build the workspace packages

   pnpm install, then pnpm --filter "./packages/*" build. The build is not optional and install does not do it for you — @specd/db and @specd/shared are imported through their gitignored dist/, so the API cannot start until they have been built once.

3. Start Postgres

   pnpm infra:up. One container, specd-postgres (pgvector on Postgres 17), mapped to host port 5433 so it can never collide with a Postgres you already run on 5432. Data lives in a named volume and survives restarts.

4. Create the schema

   pnpm db:migrate. Plain-SQL migrations applied in filename order, each in its own transaction, tracked in _specd_migrations. Idempotent, so it is also the command to run after pulling commits that added a migration.

5. Seed a playground

   pnpm db:seed writes a small fixture git repository to onboard against, so you can walk the entire pipeline without connecting anything real.

6. Run it

   pnpm dev starts the API on :4000 and the web app on :3000 in parallel. Ctrl-C stops both; Postgres stays up independently.

Verify it is actually up

curl http://localhost:4000/api/health

{ "status": "ok", "database": "up",
  "ai": "no platform key (BYO key per project)",
  "embeddings": "hash", "defaultModel": "claude-opus-5" }

"ai" reporting no key is normal and honest — agent runs will fail with a clear error until a project supplies one, and nothing else cares. If anything looks wrong, specd doctor reports config, server, database, embeddings, credential, identity and default project in dependency order and skips what an earlier failure makes unknowable.

What to do next in the app

Open localhost:3000, create an account, and the wizard walks the stations. Your first spec narrates that walk in detail; the short version is: register the seeded fixture repo, let Ground read it, merge the setup branch, draft a spec from a ticket, approve it, build it, merge.

You can also exercise the whole loop headlessly over the real HTTP API — steps that need a model are skipped and labelled, never silently passed:

pnpm --filter @specd/api loop

Common first-run problems

The longer list, including the day-two traps, is in Troubleshooting.

Next