Vercel + Tailscale

This is the recommended setup for zero-ops UI hosting. The Next.js dashboard runs on Vercel's edge network, while the pipeline server runs on your local machine (Mac, Linux, or VPS) exposed via Tailscale.

Architecture

┌─────────────────────────────────┐
│         Vercel (Cloud)          │
│  ┌───────────────────────────┐  │
│  │    GridWork HQ Dashboard  │  │
│  │    (Next.js SSR/API)      │  │
│  └─────────┬─────────────────┘  │
└─────────────┼────────────────────┘
              │ HTTPS (Bearer token)
    ┌─────────▼──────────────────────┐
    │  Tailscale Funnel / Public URL │
    └─────────┬──────────────────────┘
              │
┌─────────────┼────────────────────┐
│  Your Machine (Mac/Linux/VPS)    │
│  ┌──────────▼────────────────┐   │
│  │    Pipeline Server        │   │
│  │    + Knowledge Vault      │   │
│  │    + Claude Code CLI      │   │
│  └───────────────────────────┘   │
└──────────────────────────────────┘

Why This Split

• The dashboard is a stateless Next.js app — ideal for Vercel's edge network
• The pipeline server needs persistent memory (job queue, cron state) and local Claude Code CLI access
• Vercel serverless functions have a 60-second timeout — pipeline jobs run for minutes

Cost

1. Fork and Import to Vercel

1. Fork the gridwork-hq repo to your GitHub account
2. Go to vercel.com/new
3. Click Import Git Repository and select your fork
4. Framework preset: Next.js (auto-detected)
5. Click Deploy — the first deploy will fail (no env vars yet)

2. Run the Setup Wizard Locally

git clone https://github.com/YOUR_ORG/gridwork-hq.git
cd gridwork-hq
npm install
node setup-wizard.mjs

When Phase 4 asks for deployment target, enter vercel. Set HQ_URL to your Vercel URL (e.g., https://your-gridwork-hq.vercel.app).

3. Add Environment Variables to Vercel

Go to your Vercel project > Settings > Environment Variables and add every key from .env.local. The critical variables:

Do not set NEXTAUTH_URL — Vercel handles this automatically.

Database for Vercel

Local SQLite does not work on Vercel. Use Turso (free tier available):

1. Create a Turso database at turso.tech
2. Copy the database URL and auth token
3. Set in Vercel:
   • DATABASE_URL — your Turso URL (e.g., libsql://your-db.turso.io)
   • DATABASE_AUTH_TOKEN — your Turso auth token

4. Update GitHub OAuth App

Update your GitHub OAuth App URLs to match Vercel:

5. Set Up the Pipeline Server

On your local machine:

cd ~/agency-workspace/pipeline-server
npm install

Key environment variables in pipeline-server/.env:

PIPELINE_SERVER_TOKEN=must-match-vercel
HQ_URL=https://your-gridwork-hq.vercel.app
DUCTOR_WEBHOOK_TOKEN=must-match-vercel
ANTHROPIC_API_KEY=sk-ant-...
KNOWLEDGE_DIR=/Users/yourname/agency-workspace/knowledge
SCRIPTS_DIR=/Users/yourname/agency-workspace/.scripts

6. Expose via Tailscale

Install Tailscale

# macOS
brew install tailscale
open /Applications/Tailscale.app

# Linux
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Create a Funnel

tailscale funnel --bg 8750

This creates a public URL like https://your-machine.tail12345.ts.net/. Verify it:

tailscale funnel status
curl https://your-machine.tail12345.ts.net/health

Update Vercel

Add or update in Vercel environment variables:

PIPELINE_SERVER_URL=https://your-machine.tail12345.ts.net

7. Deploy and Test

Push to trigger a Vercel deploy:

cd ~/agency-workspace/gridwork-hq
git add config/brand.json
git commit -m "Configure brand identity"
git push origin main

Then:

1. Navigate to your Vercel URL
2. Click Sign in with GitHub
3. Go to Settings > Pipeline Server > Test Connection
4. Run a test pipeline from Mission Control

8. Custom Domain (Optional)

1. Vercel dashboard > your project > Settings > Domains
2. Enter your custom domain (e.g., hq.yourdomain.com)
3. Configure DNS: CNAME hq pointing to cname.vercel-dns.com
4. Update HQ_URL in both Vercel env vars and pipeline-server/.env
5. Update GitHub OAuth callback URL

Keeping Secrets in Sync

These secrets must match between Vercel and your pipeline server:

When rotating secrets:

1. Generate new secret: openssl rand -hex 32
2. Update in Vercel env vars and trigger a redeploy
3. Update in pipeline-server/.env and restart the server
4. Verify: Settings > Pipeline Server > Test Connection