Scaling Your Project to Production

Taking a local prototype company to a hardened, monitored, cost-governed production deployment: the 10-step checklist covering every module's production concerns in sequence.

From Sandbox to Production: Migration Checklist

What you'll learn

The complete process of moving a Paperclip company from local development to production, without data loss or agent downtime.

Migration Checklist

Phase 1: Pre-Migration (in development)

□ All agents tested with real tasks (≥10 invocations each)
□ System prompts reviewed and locked in version control
□ Budget limits set conservatively (start at 50% of expected monthly)
□ Approval policies configured and tested
□ SQL seed scripts run on a staging database successfully
□ .env file documented (not committed) with all required variables

Phase 2: Production Database

# 1. Create production database
createdb paperclip_prod

# 2. Run schema
psql $PROD_DATABASE_URL < db/schema.sql

# 3. Run seed scripts in order
psql $PROD_DATABASE_URL < db/seed.sql
psql $PROD_DATABASE_URL < db/your_company_seed.sql

# 4. Verify
psql $PROD_DATABASE_URL -c "SELECT name FROM companies;"
psql $PROD_DATABASE_URL -c "SELECT name, status FROM agents;"
psql $PROD_DATABASE_URL -c "SELECT COUNT(*) FROM issues WHERE status = 'open';"

Phase 3: Production Deploy

□ Docker Compose stack started and healthy
□ Nginx TLS configured and cert valid
□ All environment variables set (use the checklist from pcl-64)
□ Health endpoint returns 200: GET /health/ready
□ Heartbeat scheduler confirmed running in logs

Phase 4: First Production Run

# Manually trigger first heartbeat
curl -X POST https://your-domain.com/api/heartbeat/run \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"company_id": "'$COMPANY_ID'"}'

# Watch in real time
curl https://your-domain.com/api/heartbeat/runs/$RUN_ID

Phase 5: First 24 Hours Monitoring

□ Heartbeat completing without errors
□ Issues being resolved (not stuck in 'open')
□ Cost per run within expected range
□ No agent auto-paused
□ No unexpected approval requests

Data Migration from Sandbox

If you ran agents in sandbox (PGlite) and want to keep historical data:

# Export from PGlite
sqlite3 .paperclip/sandbox.db ".dump" > sandbox_dump.sql

# Note: PGlite schema may differ from PostgreSQL — use the export as reference only
# Re-create issues in production with:
psql $PROD_DATABASE_URL < historical_issues_seed.sql

Switching from One Cloud Region to Another

1. Create a pg_dump of the source database
2. Restore to the new region
3. Update DATABASE_URL in the new deployment
4. Keep the old deployment running read-only for 48 hours
5. After 48 hours with no data discrepancies, decommission the old deployment

Rollback Plan

# If the production deployment fails after migration:
# 1. Point DATABASE_URL back to the last known good database
# 2. Roll back Docker images to the previous tag
docker compose down
docker compose up -d --no-build  # uses the previous pulled images

Checkpoint ✓

• [ ] You can walk through all four phases of the production migration checklist
• [ ] You know how to verify a successful migration in the first 24 hours
• [ ] You have a rollback plan ready before starting the migration