Configuration
Environment configuration for running and deploying Oxagen: transactional email (SMTP), local-development behavior, and the storage driver.
Overview
This section covers the environment configuration that sets how Oxagen behaves in deployed and local environments. Most configuration comes from environment variables. Oxagen validates them at startup against the central env schema, so an unregistered or malformed variable stops the process instead of quietly breaking a feature.
In this section
| Page | What it covers |
|---|---|
| Email & SMTP | The SMTP_* variables behind verification and password-reset email, TLS behavior, and how a misconfigured transport reports its failure. |
| Local development | The OXAGEN_LOCAL_DEV flag, and how Oxagen relaxes deployed-only controls (email verification, token encryption, cookie hardening) on a developer machine without weakening a real deployment. |
| Storage driver | STORAGE_DRIVER and the filesystem driver (STORAGE_FS_ROOT), for blob storage locally or in CI without a Vercel Blob token. |
How environment values are loaded
- The AWS deployment loads runtime configuration from Parameter Store through the deployment tooling. Local development reads
.env.local. - Oxagen normalizes values at load time (for example, it strips surrounding quotes), so
an over-quoted value such as
"https://example.com"parses correctly. - Keep local-development flags out of deployed configuration. Local development lists the exact signals and their limits.
Validation lives in @oxagen/config. A service validates the whole schema once at boot with loadEnv() (the API server does this in apps/api/src/bootstrap.ts). A package validates only the variables it reads with requireEnv(), so importing one package never demands every variable in the monorepo:
import { requireEnv } from "@oxagen/config";
const env = requireEnv(["DATABASE_URL"] as const);
// env.DATABASE_URL: string
// env.NEO4J_URI ← type error: not requestedA missing or malformed value throws at startup and lists each failing key:
Invalid environment (required: DATABASE_URL):
- DATABASE_URL: <validation message>