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://veref:postgres@localhost:5432/veref_dev
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
VEREF_API_URL=http://localhost:8787
VEREF_API_KEY=
API_KEY_PEPPER=
VEREF_APP_URL=http://localhost:3000
VEREF_DESKTOP_API_URL=https://api.veref.work
VEREF_DESKTOP_APP_URL=https://app.veref.work
VEREF_CREDENTIAL_ENCRYPTION_KEY=
VEREF_OAUTH_STATE_SECRET=
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_WEBHOOK_SECRET=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL=/
NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL=/provisioning
OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_CHAT_MODEL=openai/gpt-oss-20b:free
OPENROUTER_MODEL_CHAIN=openai/gpt-oss-20b:free,openrouter/free
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 local CLI/API overrides; the published CLI defaults to https://api.veref.work
  • VEREF_APP_URL for local CLI login overrides; the published CLI defaults to https://app.veref.work
  • VEREF_DESKTOP_API_URL and VEREF_DESKTOP_APP_URL for explicit desktop shell overrides; desktop defaults to the cloud app/API even in dev
  • VEREF_API_KEY for API-key backed CLI commands; VITAE_API_KEY and VITAY_API_KEY are accepted aliases
  • API_KEY_PEPPER for server-side API key hashing
  • VEREF_CREDENTIAL_ENCRYPTION_KEY for encrypted OAuth credential storage
  • VEREF_OAUTH_STATE_SECRET for signed calendar OAuth state
  • 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

apps/desktop is a native shell for the cloud Veref app. bun run dev:desktop defaults to https://app.veref.work and https://api.veref.work; localhost desktop runs are only a developer harness and require explicit VEREF_DESKTOP_APP_URL / VEREF_DESKTOP_API_URL overrides.

Direct CLI entrypoint:

bun run veref -- health
bun run veref -- login --api-url http://localhost:8787 --app-url http://localhost:3000
bun run veref -- references start --json reference-request.json
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 makes ops routes unavailable unless VEREF_ENABLE_PREVIEW_FALLBACK=1 is explicitly set for development

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
Package BoundariesContributors