Generated project configuration
Environment Variables
Every clean Caspian project receives a root .env
file. It starts in development mode, includes safe framework defaults, and
receives extra sections only for the optional features selected during creation.
Two values are unique in every generated project
AUTH_SECRET is a random Base64 signing secret,
and AUTH_COOKIE_NAME is a random hexadecimal
cookie name. The placeholders below show their shape; the generator writes
real values and each new project receives different ones.
Clean-project .env
This is the baseline produced when Prisma and WebSockets are disabled.
Section numbers 1 and 9
are reserved for those optional features. Section 10
(MCP) is written for every project and stays inert until MCP is enabled.
# 2. APPLICATION RUNTIME APP_ENV="development" APP_TIMEZONE="UTC" # 3. PUBLIC URL, CORS, AND ORIGIN VALIDATION APP_BASE_URL="" CORS_ALLOWED_ORIGINS="" TRUST_FORWARDED_HEADERS="false" CORS_ALLOW_CREDENTIALS="true" CORS_ALLOWED_METHODS="GET,POST,PUT,PATCH,DELETE,OPTIONS" CORS_ALLOWED_HEADERS="Content-Type,Authorization,X-Requested-With" CORS_EXPOSE_HEADERS="" CORS_MAX_AGE="86400" # 4. AUTHENTICATION AND SESSIONS AUTH_SECRET="<generated Base64 secret>" AUTH_COOKIE_NAME="<generated 16-character hex name>" SESSION_LIFETIME_HOURS="7" # 5. OAUTH PROVIDERS — empty means disabled GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= GOOGLE_REDIRECT_URI= GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= GITHUB_REDIRECT_URI= # 6. REQUEST SECURITY MAX_CONTENT_LENGTH_MB="16" CASPIAN_REQUEST_TIMEOUT_SECONDS=20 # 7. SECURITY HEADERS — empty keeps Caspian's built-in policy CONTENT_SECURITY_POLICY= # 8. RATE LIMITING RATE_LIMIT_PAGES=200/minute RATE_LIMIT_RPC="60 per minute" RATE_LIMIT_AUTH="60 per minute" RATE_LIMIT_DEFAULT="200 per minute" RATE_LIMIT_MAX_BUCKETS=10000 RATE_LIMIT_CLEANUP_INTERVAL=60 # 10. MCP ENDPOINT — inert until mcp: true MCP_AUTH_TOKEN="<generated 64-character hex token>" # 11. CACHE CACHE_ENABLED="false" CACHE_TTL="600" CACHE_STORE="memory" CACHE_REDIS_URL= CACHE_PREFIX= # 12. LOGGING AND HEALTH PROBES — empty means on in production REQUEST_LOGS= LOG_JSON= SLOW_REQUEST_MS="1000" LOG_HEALTH_CHECKS="false" READINESS_TIMEOUT_SECONDS="2" SERVICE_NAME= # 13. MAINTENANCE MODE MAINTENANCE_MODE="false" MAINTENANCE_SECRET= MAINTENANCE_RETRY_AFTER="60" MAINTENANCE_MESSAGE= # 14. BACKGROUND JOBS AND SCHEDULER JOBS_DRIVER="memory" JOBS_DATABASE= JOBS_WORKERS="1" JOBS_CAPACITY= JOBS_SHUTDOWN_GRACE="30" JOBS_POLL_INTERVAL="1" SCHEDULER="on" # 15. LOCALIZATION APP_LOCALES= APP_DEFAULT_LOCALE= I18N_PREFIX_ROUTING="false" I18N_DIRECTORY= # 16. SERVER PROCESS UVICORN_WORKERS="1"
The generated file also contains comments explaining ownership, security implications, and defaults. The values above preserve the generator's quoting and empty-value behavior so they can be compared directly with a new project.
Sections added by feature flags
caspian.config.json decides whether these
groups exist. Tailwind, TypeScript, and backend-only mode do not add their
own environment-variable sections.
1. Database
Added by "prisma": true:
DATABASE_URL,
DB_POOL_SIZE=5,
PRISMA_CONN_PROBE_IDLE_SECONDS=30, and
PRISMA_WARN_FULL_SCAN=1.
9. WebSockets
Added by "websocket": true: allowed
origins, idle timeout (WEBSOCKET_IDLE_TIMEOUT_SECONDS,
default 120, floor 60 — client heartbeats keep live sockets open),
message-size limit, connection cap, and the per-connection message window. Production requires an explicit
WEBSOCKET_ALLOWED_ORIGINS value.
Optional feature configuration
10. MCP endpoint
Every generated project receives this section, but it stays inert until
caspian.config.json has "mcp": true,
so enabling MCP later needs no new secret. The generated token is unique to the
project; the placeholder below intentionally does not contain a usable secret.
# ============================================================================= # 10. MCP ENDPOINT # Enforced by: main.py MCPAuthMiddleware; tools in src/lib/mcp/mcp_server.py # Inert until caspian.config.json has mcp: true; kept here so the option is always available. # ============================================================================= # Bearer token required to call /mcp. The MCP app is mounted outside the page # routing tree, so AuthMiddleware does NOT protect it, and its tools enumerate # the workspace file inventory and component map. # # generated -> every request needs "Authorization: Bearer <token>" # # REQUIRED IN PRODUCTION for the endpoint to work at all. MCP_AUTH_TOKEN="<generated 64-character hexadecimal token>"
Separate auth boundary
Browser sessions and private-route rules do not authorize MCP clients.
The mounted endpoint is protected directly by
MCPAuthMiddleware.
Development fallback
With no token, local development keeps the endpoint open for trusted tooling such as MCP Inspector. Do not expose that configuration publicly.
Production fails closed
With no token, production returns 503.
A missing or invalid bearer credential returns 401.
Client request header
Authorization: Bearer <MCP_AUTH_TOKEN>
Store the production value in the hosting platform's secret manager, use a distinct token per environment, and rotate it if it is exposed. Never commit the generated value or place it in browser code.
See the MCP Server guide for the mounted transport, CORS ownership, tools, and local inspection workflow.
Protect local values before an update
The Caspian project update workflow regenerates .env
unless it appears in excludeFiles. After creating
a project, add the entry below before customizing secrets or provider values.
"excludeFiles": ["./.env"]
An excluded file will not receive newly generated variables when a feature is
enabled later. Merge the new feature section manually instead of removing the
protection and overwriting the file. Keep .env
out of version control and set production secrets in the hosting platform.
CLI configuration
Control feature flags and protect app-owned files during updates.
Production environment
Replace development defaults with platform-managed production values.