Deploy (Docker + Vercel)

Start Postgres

docker run -d \
  --name handoff-registry \
  -e POSTGRES_DB=handoff_registry \
  -e POSTGRES_USER=handoff \
  -e POSTGRES_PASSWORD=changeme \
  -p 5433:5432 \
  postgres:16-alpine

until docker exec handoff-registry pg_isready -U handoff; do sleep 1; done

Start the registry from handoff-app

cd /path/to/handoff-app

DATABASE_URL=postgresql://handoff:changeme@localhost:5433/handoff_registry \
AUTH_SECRET=$(openssl rand -hex 32) \
HANDOFF_SYNC_SECRET=dev-registry-secret \
  npm run build:registry && \
  cd src/app && npx next start -p 4002

# Or for hot-reload development: npm run dev (from the handoff-app root)

The registry runs at http://localhost:4002. npm run build:registry applies pending migrations as a build step (scripts/migrate-on-deploy.mjs) before next build runs. Outside Vercel, instrumentation.ts also applies pending migrations at process startup as a fallback, see First-admin setup for the /setup flow that follows.

Point a workspace at it

cd my-design-system

# Device OAuth: opens a browser, saves a token to .handoff/cli-auth.json
handoff-app login --url http://localhost:4002

# Or shared-secret auth via env vars
echo 'HANDOFF_CLOUD_URL=http://localhost:4002' >> .env
echo 'HANDOFF_CLOUD_TOKEN=dev-registry-secret' >> .env

handoff-app sync-status   # confirm the connection

Push content

handoff-app push:all

Visit http://localhost:4002/ to see the design system. See Workspace → CLI reference for every push/ push:all flag.

Create the Vercel project

In the Vercel dashboard: Add New → Project → Import Git Repository, pointing at the handoff-app repository, branch main. Vercel auto-detects the committed vercel.json at the repo root:

{
  "framework": "nextjs",
  "installCommand": "npm install",
  "buildCommand": "npm run build:registry",
  "outputDirectory": "src/app/.next",
  "crons": [
    { "path": "/api/handoff/ai/design-jobs/run", "schedule": "* * * * *" }
  ]
}

The crons entry drains the AI design-image generation queue once a minute; it needs CRON_SECRET set (see Environment variables) or the route hard-fails with a 503 and queued images never render.

Leave Root Directory blank (repo root). Don't click Deploy yet: env vars first.

Add Postgres

Storage → Connect Store → Create New → Postgres on the new project. Vercel auto-injects DATABASE_URL (and POSTGRES_*) into the project's env vars. An existing Postgres instance from another project can be attached instead (Storage → Connect Store → Existing).

Set the remaining env vars

Settings → Environment Variables, all environments, see Environment variables for the full reference:

HANDOFF_REGISTRY_MODE is not needed. It's only read by the deprecated vercel-build command, which the current build path doesn't run; DATABASE_URL alone puts the app in registry mode.

Deploy

Click Deploy. vercel.json runs npm run build:registry, which compiles the CLI, bundles the MCP Apps, applies pending database migrations (scripts/migrate-on-deploy.mjs), then runs next build into src/app/.next/. Migrations happen at build time, not on the first request, instrumentation.ts deliberately skips migrating when VERCEL is set, because a serverless instance can be frozen mid-migration while still holding the advisory lock. Once the build lands, the app redirects to /setup because no users exist yet.

Complete first-admin setup, then push

Visit the deployment URL, create the first admin account at /setup, then point a workspace at it the same way as the Docker path above (handoff-app login --url <production URL>, or HANDOFF_CLOUD_URL/HANDOFF_CLOUD_TOKEN), and handoff-app push:all. See First-admin setup for the full first-boot walkthrough.