| name | setup-dev |
| description | Bootstrap the local development environment — checks prerequisites, starts Supabase, generates env files, launches dev servers |
| disable-model-invocation | true |
Setup Dev Environment
Bootstrap everything needed to run Butler locally.
Steps
1. Check Node.js version
Butler requires Node.js 22+ (Wrangler dependency).
node --version
If below v22, stop and tell the user:
"Butler requires Node.js 22+. You're on [version]. Upgrade via nvm install 22 or volta install node@22."
2. Check Docker is running
Local Supabase requires Docker.
docker info >/dev/null 2>&1
If Docker is not running, stop and tell the user:
"Docker is required for local Supabase. Start Docker Desktop and retry."
3. Start local Supabase
supabase start
This takes 1-2 minutes on first run (pulls Docker images). Extract the API URL and anon key from the output.
If supabase CLI is not installed, tell the user:
"Install the Supabase CLI: brew install supabase/tap/supabase"
4. Generate frontend .env
Create packages/frontend/.env with the values from supabase status:
supabase status -o json
Write to packages/frontend/.env:
VITE_SUPABASE_URL=<API URL from status>
VITE_SUPABASE_ANON_KEY=<anon key from status>
Do NOT commit this file — it is gitignored.
5. Build shared package
pnpm --filter @butler/shared build
6. Start dev servers
pnpm --filter @butler/api dev &
pnpm --filter @butler/frontend dev &
7. Verify
- API health:
curl http://localhost:8787/health
- Frontend: open
http://localhost:5173 in browser
Report which services are running and any that failed.
