Skip to Content
Local Development

Local Development

This page documents the current local setup expected by the repo.

Prerequisites

  • Bun 1.3.13 as declared in the root packageManager
  • Postgres if you want real persistence
  • Redis if you want parity with the current env template
  • local claude and codex CLIs only if you are exercising the desktop bridge workflows

Install and bootstrap

bun install --frozen-lockfile
./skills.sh install
bun run db:generate

Optional database setup commands:

bun run db:migrate:dev
bun run db:push

Environment variables

Current .env.example keys:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/veref
REDIS_URL=redis://localhost:6379
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_WEB_URL=http://localhost:3001
NEXT_PUBLIC_DOCS_URL=http://localhost:3101
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
RESEND_API_KEY=
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_MESSAGING_SERVICE_SID=

Additional surface-specific environment use visible in source:

  • VEREF_API_URL for the CLI, defaulting to http://localhost:8787
  • PLASMO_PUBLIC_APP_URL for the browser extension, defaulting to http://localhost:3000
  • PORT overrides per-surface dev ports

Default local ports

  • recruiter app: 3000
  • marketing web: 3001
  • docs: 3101
  • API: 8787

Desktop, mobile, extension, and CLI use their own runtime tooling rather than fixed HTTP ports in the same way.

Common entrypoints

Start individual surfaces:

bun run dev:app
bun run dev:web
bun run dev:docs
bun run dev:api
bun run dev:desktop
bun run dev:mobile
bun run dev:extension
bun run dev:cli

Direct CLI entrypoint:

bun run veref -- health
bun run veref -- ops feed --tenant demo-agency

The desktop runtime and local agent workflows depend on the repo links being healthy.

Use:

./skills.sh install
./skills.sh status

What healthy links mean:

  • runtime skills are read from skills/
  • agent skills are read from .agents/skills
  • agent memory is read from .agents/memory
  • .claude/* and .codex/* symlinks resolve into .agents/*

Development modes

Preview-friendly mode

You can still inspect large parts of the product without every external dependency configured.

  • missing OpenRouter key returns unconfigured LLM responses
  • missing Resend or Twilio credentials yields preview communication behavior
  • missing database configuration can force preview-only data paths

Fully configured mode

For closer runtime parity, configure:

  • DATABASE_URL
  • Clerk keys
  • OPENROUTER_API_KEY
  • Resend key
  • Twilio credentials

Local verification

Repo-wide verification:

bun run typecheck
bun run test
bun run build

Docs-only validation when iterating on docs content:

bun run --filter @veref/docs build
Last updated on
ContributorsDeployment & Operations