Environment Variables Reference

For: DevOps engineers and platform administrators Last Updated: 2026-04-09 Location: Set in .env.local (development) or inject via CI/CD / cloud secrets manager (production)

---

Quick Start Core Application Database Authentication (Auth0) Encryption & Secrets Redis / Upstash Monitoring (Sentry) Billing (Stripe) AI Providers OAuth Integrations Email / SMTP Agent Communication AWS Provisioning Cloud Marketplaces Cron & Automation Tenant Configuration Go Agent Developer Tools (MCP / LSP / CLI) Observability & Deployment Metadata

---

Quick Start

Minimum variables needed for local development:

Required minimum DATABASEURL=postgresql://user:pass@localhost:5432/shielda AUTH0SECRET=<random-32-bytes AUTH0BASEURL=http://localhost:3000 AUTH0ISSUERBASEURL=https://your-tenant.auth0.com AUTH0CLIENTID=<your-client-id AUTH0CLIENTSECRET=<your-client-secret NEXTPUBLICAPPURL=http://localhost:3000 NEXTPUBLICBASEURL=http://localhost:3000 ENCRYPTIONSECRET=<32-char-hex-string

---

Core Application

Variable Required Default Description NODEENV Yes development development, test, or production NEXTPUBLICAPPURL Yes — Full URL of the application (e.g., https://app.shielda.io) NEXTPUBLICBASEURL Yes — Base URL for API calls (same as APPURL in most cases) NEXTPUBLICAPPDOMAIN No — Domain for multi-tenant routing (e.g., shielda.io). Subdomains resolve to {slug}.shielda.io

Where to inject: Next.js runtime environment. NEXTPUBLIC vars are embedded at build time.

---

Database

Variable Required Default Description DATABASEURL Yes — PostgreSQL connection string. Format: postgresql://user:password@host:5432/dbname?sslmode=require

Where to inject: Server-side only. Never expose to client. Production notes: Use connection pooling (e.g., PgBouncer, Neon pooler, Supabase pooler) Enable sslmode=require for production The schema uses 81 tables with RLS tenant isolation

---

Authentication (Auth0)

Variable Required Default Description AUTH0SECRET Yes — Random secret for session encryption (≥32 bytes). Generate with openssl rand -hex 32 AUTH0BASEURL Yes — Application URL (must match NEXTPUBLICAPPURL) AUTH0ISSUERBASEURL Yes — Auth0 tenant URL (e.g., https://shielda.us.auth0.com) AUTH0CLIENTID Yes — Auth0 application client ID AUTH0CLIENTSECRET Yes — Auth0 application client secret

Where to inject: Server-side only. Auth0 Dashboard Configuration: Create a "Regular Web Application" Set Allowed Callback URLs: https://app.shielda.io/api/auth/callback Set Allowed Logout URLs: https://app.shielda.io Enable Refresh Token Rotation Set Token Expiration: 8 hours (absolute), 30 minutes (inactivity)

---

Encryption & Secrets

Variable Required Default Description ENCRYPTIONSECRET Yes — 32-character hex string for AES-256-GCM encryption of secrets vault. Generate with openssl rand -hex 16 SHIELDASECRET Yes — Platform-level signing secret for internal operations JWTSECRET Yes — Secret for agent JWT token signing/validation TOKENHASHSECRET No — HMAC secret for CI/agent token hashing. Falls back to AUTH0SECRET if not set

Where to inject: Server-side only. Store in a secrets manager (AWS Secrets Manager, Vault, etc.) Critical: Rotating ENCRYPTIONSECRET requires re-encrypting all vault entries. Rotating JWTSECRET invalidates all agent tokens.

---

Redis / Upstash

Variable Required Default Description UPSTASHREDISRESTURL Yes (prod) — Upstash Redis REST API URL UPSTASHREDISRESTTOKEN Yes (prod) — Upstash Redis REST API token REDISURL No — Standard Redis connection URL (alternative to Upstash — checked first if set)

Where to inject: Server-side only. Usage: Rate limiting (multi-tier), caching, session store. Fallback: In development, rate limiting uses in-memory store if Redis is not configured.

⚠️ Security note (SA-17): Without Redis, each Next.js instance maintains its own in-memory rate counter. In multi-instance deployments (e.g. Vercel Functions, Kubernetes replicas), the effective rate limit is multiplied by instance count. Always configure Redis/Upstash in production to ensure rate limits are enforced globally across all instances.

---

Monitoring (Sentry)

Variable Required Default Description SENTRYDSN No — Server-side Sentry DSN for error tracking NEXTPUBLICSENTRYDSN No — Client-side Sentry DSN (embedded at build time)

Where to inject: Both server and client. NEXTPUBLIC prefix exposes to browser. Configuration: Production: 10% server traces, 5% client traces PII scrubbing enabled (IP addresses stripped, no user data in breadcrumbs) Session replay: 0% normal, 10% on error (production) See docs/TELEMETRYPOLICY.md for complete data collection details

---

Billing (Stripe)

Variable Required Default Description STRIPESECRETKEY Yes (prod) — Stripe API secret key (sklive... or sktest...) STRIPEWEBHOOKSECRET Yes (prod) — Stripe webhook endpoint signing secret (whsec...) ENFORCEBILLING No false Set to true to enforce billing limits in non-production environments. In production, billing is always enforced regardless of this flag

Where to inject: Server-side only. Stripe Dashboard Setup: Create webhook endpoint: https://app.shielda.io/api/billing/webhook Subscribe to events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paymentsucceeded, invoice.paymentfailed Get the webhook signing secret → set as STRIPEWEBHOOKSECRET

---

AI Providers

Variable Required Default Description ANTHROPICAPIKEY Yes — Anthropic API key for Claude (primary AI provider) OPENAIAPIKEY No — OpenAI API key (fallback / GPT-based agents)