This guide walks you through acquiring every credential required to run SecureFlow locally.
Option A — Local PostgreSQL
- Install PostgreSQL.
- Create a database:
CREATE DATABASE secureflow;
- Set in
.env:DATABASE_URL="postgresql://postgres:<your_password>@localhost:5432/secureflow" DATABASE_POOL_URL="postgresql://postgres:<your_password>@localhost:5432/secureflow" # same as DATABASE_URL for local dev DB_POOL_MAX=10
Option B — Neon (recommended for cloud/serverless)
- Sign up at neon.tech and create a project.
- From the Connection Details panel, copy:
- Direct URL →
DATABASE_URL - Pooled URL →
DATABASE_POOL_URL
- Direct URL →
- Set
DB_POOL_MAX=10(or adjust based on your plan's connection limit).
After setting the URLs, run:
npm run db:gen
npm run db:migrate
npm run db:seed- Sign up at console.groq.com.
- Go to API Keys → Create API Key.
- Copy the key →
GROQ_API_KEY. GROQ_MODELdefaults toopenai/gpt-oss-20b. Change only if you want a different supported model (Groq's deprecation page lists the ones that have been shut down).
GROQ_API_KEY="gsk_..."
GROQ_MODEL="openai/gpt-oss-20b"- Go to GitHub → Settings → Developer Settings → GitHub Apps → New GitHub App.
- Fill in:
- Homepage URL:
http://localhost:9002 - Webhook URL: your ngrok URL +
/api/webhooks/githubngrok http 9002 # copy the https:// forwarding URL - Webhook Secret: any random string (e.g.
openssl rand -hex 20) →GITHUB_WEBHOOK_SECRET
- Homepage URL:
- Set Repository Permissions: Contents
Read, Pull RequestsRead & Write, ChecksRead & Write, Code scanning alertsRead & Write.- Code scanning alerts (the
security_eventspermission) is what lets SecureFlow publish findings to the repository's Security → Code scanning tab. Without it the scan still runs and still posts its check run; only the upload is skipped. - GitHub accepts these uploads for public repositories, and for private repositories only with GitHub Advanced Security enabled. A private repository without it answers
403, which SecureFlow logs and moves past.
- Code scanning alerts (the
- Subscribe to events:
Pull request,Installation,Installation repositories. - Click Create GitHub App, then:
- Copy App ID →
GITHUB_APP_ID - Scroll to Private Keys → Generate a private key → download
.pem→ paste its full contents (including headers) intoGITHUB_PRIVATE_KEY, replacing newlines with\n:awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' your-app.pem - Copy the app's public URL →
GITHUB_APP_URL(e.g.https://github.com/apps/your-app-name)
- Copy App ID →
GITHUB_APP_ID="123456"
GITHUB_WEBHOOK_SECRET="your_random_secret"
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_APP_URL="https://github.com/apps/your-app-name"These power the Sign in with GitHub button via NextAuth.js.
- In the same GitHub App you created above, scroll to OAuth Credentials.
- Copy Client ID →
GITHUB_CLIENT_ID. - Click Generate a new client secret →
GITHUB_CLIENT_SECRET. - Generate
AUTH_SECRET:openssl rand -base64 32
- Set
AUTH_URLto your local dev URL:AUTH_URL="http://localhost:9002"
GITHUB_CLIENT_ID="Iv1.abc123"
GITHUB_CLIENT_SECRET="your_client_secret"
AUTH_SECRET="your_generated_secret"
AUTH_URL="http://localhost:9002"Redis is optional for local development. Leave all three blank if you don't need caching/rate-limiting locally.
For production or if your feature branch requires it:
- Sign up at upstash.com and create a Redis database.
- From the database dashboard, copy:
- Redis URL (starts with
rediss://) →REDIS_URL - REST URL →
UPSTASH_REDIS_REST_URL - REST Token →
UPSTASH_REDIS_REST_TOKEN
- Redis URL (starts with
REDIS_URL="rediss://default:<token>@<host>:6379"
UPSTASH_REDIS_REST_URL="https://<host>.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your_token"These are only needed for advanced policy features. Leave blank for standard local development.
If ArmorIQ becomes slow or unreachable, a circuit breaker opens after 3 consecutive upstream failures (timeouts, rate limits, 5xx, network errors) and ArmorIQ-gated actions are refused until it answers a probe. Both knobs are optional:
ARMORIQ_CIRCUIT_FAILURE_THRESHOLD— consecutive failures before the circuit opens (default3).ARMORIQ_CIRCUIT_RESET_TIMEOUT_MS— milliseconds before a probe is allowed (default30000).
SecureFlow is organized as an npm workspace monorepo with the root project and the cli/ workspace (secureflow-cli). All dependencies are hoisted and managed under a single source of truth at package-lock.json in the project root.
- Install all dependencies across root and workspaces:
npm install
- Build CLI package via workspace:
npm run cli:build # or directly with npm workspace: npm run build --workspace=cli - Run CLI tests via workspace:
npm run cli:test # or directly with npm workspace: npm run test --workspace=cli
- Typecheck CLI workspace:
npm run cli:typecheck
Once SecureFlow is running, sign in to the dashboard at http://localhost:9002/dashboard. The "Get Started with SecureFlow" onboarding checklist guides you through verifying:
- GitHub App installed: Verifies GitHub App connection to your user account.
- At least one repository connected: Ensures repository sync has occurred.
- Webhook delivery received: Click "Send Test Event" to simulate and verify an HMAC-SHA256 signed GitHub ping delivery without scanning real code.
- At least one policy enabled: Confirms guardrails under
/dashboard/policies. - First scan completed: Verifies that opening or updating a PR executes the scan pipeline.
The checklist is dismissible and automatically hides once all 5 setup steps are completed.
[ ] DATABASE_URL set and `npm run db:migrate` succeeded
[ ] GROQ_API_KEY set
[ ] GitHub App created — APP_ID, WEBHOOK_SECRET, PRIVATE_KEY, APP_URL set
[ ] GitHub OAuth credentials set — CLIENT_ID, CLIENT_SECRET
[ ] AUTH_SECRET generated and set
[ ] ngrok running and Webhook URL updated in GitHub App settings
[ ] npm install completed with single root package-lock.json
[ ] npm run dev starts without errors at http://localhost:9002