Local Dev Skill

Start the full local development stack with optional tunnel for webhook testing.

Quick Commands

Workflow: Start Dev

Step 1: Check Prerequisites

bash
1# Check node, pnpm, pm2
2node --version && pnpm --version && pm2 --version 2>/dev/null || echo "MISSING: install pm2 globally"

If pm2 is missing: npm install -g pm2

Step 2: Start Dev Servers

bash
1cd /Users/benknight/Code/act-global-infrastructure
2./dev start

This starts via PM2:

• act-frontend: Next.js on http://localhost:3002
• act-api: API server on http://localhost:3456

Step 3: Verify

bash
1# Wait for servers to be ready
2sleep 5
3
4# Check frontend
5curl -s -o /dev/null -w "Dashboard: %{http_code}\n" http://localhost:3002/
6
7# Check API
8curl -s -o /dev/null -w "API: %{http_code}\n" http://localhost:3456/api/health 2>/dev/null || echo "API: standalone API not needed (Next.js API routes handle it)"
9
10# PM2 status
11pm2 status

Step 4: Report

Local dev environment ready:
- Dashboard: http://localhost:3002
- API routes: http://localhost:3002/api/...

Workflow: Tunnel (for webhook testing)

Use this when testing Telegram bot, GHL webhooks, or Xero webhooks locally.

Step 1: Start Dev Servers (same as above)

Step 2: Start Cloudflared Tunnel

IMPORTANT: Use --config /dev/null to avoid the catch-all 404 from existing config.yml.

bash
1cloudflared tunnel --config /dev/null --url http://localhost:3002 2>&1 &

Wait a few seconds, then grab the tunnel URL from the output (looks like https://something-random.trycloudflare.com).

Step 3: Set Telegram Webhook (if testing bot)

bash
1TUNNEL_URL="<the cloudflared URL>"
2TELEGRAM_BOT_TOKEN="<from .env.local>"
3
4curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
5  -d "url=${TUNNEL_URL}/api/telegram/webhook" \
6  -d "secret_token=<TELEGRAM_WEBHOOK_SECRET from .env.local>"

Verify:

bash
1curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo" | python3 -m json.tool

Step 4: Report

Tunnel active:
- Public URL: <tunnel URL>
- Telegram webhook: set to <tunnel URL>/api/telegram/webhook
- Test by sending a message to the bot

Step 5: Cleanup (when done)

IMPORTANT: Reset webhook to production URL when done testing locally.

bash
1curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
2  -d "url=https://command.act.place/api/telegram/webhook" \
3  -d "secret_token=<TELEGRAM_WEBHOOK_SECRET>"

Kill the tunnel:

bash
1pkill -f cloudflared 2>/dev/null

Workflow: Start Cron Scripts

bash
1cd /Users/benknight/Code/act-global-infrastructure
2./dev cron

This starts PM2 cron jobs:

• notion-sync — every 5 min
• imessage-sync — every 15 min
• daily-briefing — 7am AEST
• knowledge-pipeline — 8am AEST
• data-freshness — every 6h
• Plus: storyteller sync/link, embed-imessages, detect-episodes, agent-learning, meeting-sync

Workflow: Status & Logs

bash
1# Status of all PM2 processes
2pm2 status
3
4# Tail all logs
5pm2 logs --lines 50
6
7# Tail specific service
8pm2 logs act-frontend --lines 30
9
10# Check for errors
11pm2 logs --err --lines 20

Workflow: Stop

bash
1# Stop dev servers only
2./dev stop
3
4# Stop cron scripts only
5./dev stop-cron
6
7# Stop everything
8pm2 stop all

Ports & URLs

Common Issues

Environment Checklist

These env vars must be in .env.local for full local dev:

Required:

• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
• ANTHROPIC_API_KEY
• OPENAI_API_KEY

For Telegram bot testing:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_WEBHOOK_SECRET
• TELEGRAM_AUTHORIZED_USERS

For email/calendar:

• GOOGLE_SERVICE_ACCOUNT_KEY
• GOOGLE_DELEGATED_USERS
• GOOGLE_CALENDAR_ID

For finance:

• XERO_CLIENT_ID, XERO_CLIENT_SECRET, XERO_TENANT_ID, XERO_REFRESH_TOKEN