Quick Start

This guide takes you from a fresh GridWork HQ download to a running dashboard. Total time: under 10 minutes.

Step 1: Extract and Set Up the Directory

mkdir -p ~/agency-workspace
cd ~/agency-workspace

# Extract the GridWork HQ package
unzip gridwork-hq.zip

Your workspace should look like this:

~/agency-workspace/
├── gridwork-hq/           # Next.js dashboard
├── pipeline-server/       # Pipeline execution engine
├── knowledge/             # Knowledge vault (docs, templates, memory)
└── .scripts/              # Shell automation scripts (auto-created)

Step 2: Install Dependencies

cd ~/agency-workspace/gridwork-hq
npm install

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

If you have bun installed, use bun install instead for faster installs.

Step 3: Run the Setup Wizard

cd ~/agency-workspace/gridwork-hq
node setup-wizard.mjs

The wizard walks you through 5 phases:

1. Agency Identity — Your agency name, domain, contact email, timezone
2. Theme & Branding — Primary color, background color, fonts, sidebar title
3. Integrations — API keys for Notion, Stripe, Anthropic, GitHub, Vercel, etc.
4. Infrastructure — Deployment target, file paths, pipeline server port
5. AI Configuration — Telegram bot, default model tier, cron preferences

Press Enter to accept defaults (shown in brackets). You can skip optional API keys and add them later.

What Gets Written

Step 4: Set Up the Knowledge Vault

cd ~/agency-workspace

# Copy the knowledge vault template
cp -r gridwork-hq/knowledge-template knowledge

# Initialize as a git repo
cd knowledge
git init
git add .
git commit -m "Initial knowledge vault from template"

Step 5: Start the Pipeline Server

cd ~/agency-workspace/pipeline-server
bun run dev

You should see:

[INFO] Pipeline server listening on port 8750
[INFO] Max parallel jobs: 3
[INFO] Cron jobs loaded: 12
[INFO] Auth: Bearer token required

Verify it is running:

curl http://localhost:8750/health
# Returns: {"status":"ok","uptime":...}

Step 6: Start the Dashboard

Open a new terminal:

cd ~/agency-workspace/gridwork-hq
npm run dev

Step 7: Log In

Open http://localhost:3000 in your browser and click Sign in with GitHub.

If authentication fails, check:

• GITHUB_ID and GITHUB_SECRET are correct in .env.local
• The callback URL in your GitHub OAuth App is http://localhost:3000/api/auth/callback/github
• NEXTAUTH_SECRET is set (generate with openssl rand -base64 32)
• NEXTAUTH_URL=http://localhost:3000

Step 8: Load Demo Data (Optional)

On first login, you will see a WelcomeBanner with a 5-step onboarding checklist. Click Load Demo Data to populate the dashboard with sample clients, pipeline jobs, and activity items. This helps you explore the interface before adding real data.

To remove demo data later, click Clear Demo Data from the same banner.

What is Next

• Run your first pipeline to see the AI system in action
• Configure integrations for Notion, Stripe, and other services
• Add your first real client to the knowledge vault
• Set up Telegram for pipeline and cron notifications