Install GridWork HQ on your local Mac or Linux machine for development and solo agency operations.

Local Setup (Mac/Linux)

This is the recommended setup for development and solo operators. Both the dashboard and pipeline server run on your local machine.

1. Clone and Install

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

# Clone both packages
git clone https://github.com/YOUR_ORG/gridwork-hq.git
git clone https://github.com/YOUR_ORG/pipeline-server.git

# Install dependencies
cd ~/agency-workspace/gridwork-hq && npm install
cd ~/agency-workspace/pipeline-server && npm install

2. Run the Setup Wizard

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

The wizard runs 5 interactive phases. See the Quick Start for details on each phase.

3. Set Up the Knowledge Vault

cd ~/agency-workspace

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

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

To push to a remote:

git remote add origin https://github.com/YOUR_ORG/knowledge.git
git push -u origin main

4. Set Up Shell Scripts Directory

mkdir -p ~/agency-workspace/.scripts

Shell scripts for cron jobs (email-sync, push-activity, todo-sync) go here. The pipeline server references them via the SCRIPTS_DIR environment variable.

5. Notion Database Setup

You need two Notion databases. See the full Notion integration guide for detailed setup, or follow the quick version here.

Leads Database

Create a Notion database with these properties:

Property	Type	Notes
Name	Title	Business name
Status	Select	New, Contacted, Responded, Meeting, Proposal, Won, Lost
Category	Select	Business category
Notes	Rich text	Free-form notes
Email	Email	Contact email
URL	URL	Business website
Phone	Phone	Contact phone
Area	Select	Geographic area

Clients Database

Create another database:

Property	Type	Notes
Name	Title	Business name
Status	Select	Onboarding, Active, Retainer, Paused, Completed
Tier	Select	Starter, Growth, Premium
MRR	Number	Monthly recurring revenue
Domain	URL	Client's live domain
Contact	Email	Primary contact email
Launch Date	Date	Site launch date

Share both databases with your Notion integration (click ... > Connections > select your integration).

Copy the database IDs from each database URL and add them to .env.local:

NOTION_LEADS_DB=your-leads-database-id
NOTION_CLIENTS_DB=your-clients-database-id

6. GitHub OAuth Setup

Go to github.com/settings/applications/new
Set:
- Application name: GridWork HQ
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github
Copy Client ID to GITHUB_ID and generate a Client Secret for GITHUB_SECRET

7. Database (SQLite)

GridWork HQ uses SQLite via Drizzle ORM. The database file is auto-created at ./data/gridwork-hq.db on first run. No configuration required.

To use a custom path:

# In .env.local
DATABASE_URL=file:/path/to/your/gridwork-hq.db

After pulling updates with schema changes:

cd ~/agency-workspace/gridwork-hq
bun run migrate

8. Start the Pipeline Server

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

Verify:

curl http://localhost:8750/health

Auto-Start on macOS (LaunchAgent)

Create ~/Library/LaunchAgents/com.agency.pipeline-server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agency.pipeline-server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>pipeline-server/src/server.ts</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/YOURNAME/agency-workspace/pipeline-server</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/pipeline-server.stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/pipeline-server.stderr.log</string>
</dict>
</plist>

Load it:

# Update paths to match your system
sed -i '' "s|/usr/local/bin/node|$(which node)|g" \
  ~/Library/LaunchAgents/com.agency.pipeline-server.plist
sed -i '' "s|YOURNAME|$(whoami)|g" \
  ~/Library/LaunchAgents/com.agency.pipeline-server.plist

launchctl load ~/Library/LaunchAgents/com.agency.pipeline-server.plist

Auto-Start on Linux (systemd)

Create /etc/systemd/system/agency-pipeline.service:

[Unit]
Description=Agency Pipeline Server
After=network.target

[Service]
Type=simple
User=YOURUSER
WorkingDirectory=/home/YOURUSER/agency-workspace/pipeline-server
ExecStart=/usr/bin/bun run pipeline-server/src/server.ts
Restart=on-failure
RestartSec=10
EnvironmentFile=/home/YOURUSER/agency-workspace/pipeline-server/.env

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable agency-pipeline
sudo systemctl start agency-pipeline
journalctl -u agency-pipeline -f

9. Start the Dashboard

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

Open http://localhost:3000 and sign in with GitHub.

10. Claude Code Configuration

Configure Claude Code

Create or update ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(node *)",
      "Read",
      "Write",
      "Edit"
    ]
  }
}

MCP Servers

For full pipeline functionality, configure these MCP servers in your Claude Code settings:

MCP Server	Purpose	Required For
Notion	CRM data access	prospect, propose, friday-update, scope-audit
GitHub	Repo operations	build, internal-audit
Playwright	Site screenshots	audit, seo, internal-audit

11. Tailscale (Optional)

If you plan to deploy the dashboard to Vercel while keeping the pipeline server local:

brew install tailscale
tailscale funnel --bg 8750

This gives you a public URL for your pipeline server. See the Vercel + Tailscale guide for the full setup.

Next Steps

Add your logo to gridwork-hq/public/brand/logo.svg
Customize your brand in config/brand.json
Run your first pipeline
Configure Telegram notifications for cron alerts
Set up cron jobs for automated operations

Local (Mac/Linux)