Restart AgentForge Dev Services

Perform a clean bounce of the backend and UI. Follow the steps in order and stop if any mandatory step fails.

Environment

• Use Node 22 via nvm: run nvm use (the repo ships a .nvmrc pinning Node 22; the script enforces >=22.12 / arm64 on Apple Silicon).
• Backend port: 3100
• UI port: 5173
• Postgres: Docker container named agentforge-postgres on localhost:5433 (matches the default DATABASE_URL in foundry/.env.example).

Steps

1. Kill all existing dev processes

Run these in parallel where possible:

pkill -9 -f "tsx watch" 2>/dev/null
pkill -9 -f "node.*vite" 2>/dev/null
pkill -9 -f "scripts/dev.mjs" 2>/dev/null
sleep 2
# also free the ports if anything stale is still holding them
lsof -tiTCP:3100 -sTCP:LISTEN | xargs -r kill -9 2>/dev/null
lsof -tiTCP:5173 -sTCP:LISTEN | xargs -r kill -9 2>/dev/null

Verify no dev processes remain:

ps aux | grep -E "tsx watch|node.*vite|dev\.mjs" | grep -v grep | wc -l

Must print 0. If not, repeat pkill -9 with the specific PIDs.

2. Ensure Postgres is running

docker ps --filter "name=agentforge-postgres" --format "{{.Status}}"

If empty or shows Exited:

docker start agentforge-postgres
sleep 3

If the container doesn't exist at all, create it (matches the quickstart in foundry/README.md):

docker volume create agentforge_pg_data
docker run -d --name agentforge-postgres --restart unless-stopped \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=ai_orchestrator \
  -p 5433:5432 \
  -v agentforge_pg_data:/var/lib/postgresql/data \
  postgres:16

3. Verify backend prerequisites

Only run these if they would otherwise fail -- check first, don't blindly reinstall.

• foundry/.env exists. If missing: cp foundry/.env.example foundry/.env
• foundry/node_modules/ exists. If missing: cd foundry && pnpm install --ignore-scripts
• foundry/src/generated/prisma/client.js exists (Prisma client is generated). If missing OR if the schema changed recently: cd foundry && npx prisma generate

If the Prisma schema is ahead of the DB (e.g. new columns causing PrismaClientValidationError: Unknown argument), sync the DB:

cd foundry && npx prisma db push && npx prisma generate

4. Start the dev server

Run from the repo root, in the background (it's long-running):

nvm use && npm run dev

Use block_until_ms: 0 so the shell tool backgrounds it immediately and writes to the terminal log file.

5. Verify both services respond

Wait ~10 seconds, then:

curl -s -o /dev/null -w "backend: %{http_code}\n" http://localhost:3100/health
curl -s -o /dev/null -w "ui: %{http_code}\n" http://localhost:5173/

Both must return 200. If either returns 000, read the terminal log file, strip ANSI (sed 's/\x1b\[[0-9;]*m//g'), and diagnose.

6. (Optional) Verify LAN / VPN exposure

The UI is configured in ui/vite.config.ts with server.host: true. The backend binds to 0.0.0.0:3100 in foundry/src/server.ts. If the user has set up a LAN/VPN hostname (Tailscale, ngrok, etc.) and asks for it to be verified, they should provide the hostname; then:

# replace $HOSTNAME with the user-provided value
curl -s -o /dev/null -w "remote backend: %{http_code}\n" http://$HOSTNAME:3100/health
curl -s -o /dev/null -w "remote ui: %{http_code}\n"      http://$HOSTNAME:5173/

Both must return 200. If the UI returns 403, add the hostname to ui/vite.config.ts server.allowedHosts.

Common failure modes and fixes

Final report

When complete, report:

• Local URLs: http://localhost:3100 (backend /health) and http://localhost:5173/ (UI)
• Any optional remote URLs verified in step 6
• Any non-fatal warnings from the log