Local development

OverviewCopy Anchor Link

A few controls are on in deployed environments and off on a developer machine: mandatory email verification, the mandatory OAuth-token-encryption key, and hardened cookies. Rate limits stay on locally. Only the Playwright test harness turns them off. Oxagen decides which mode it is in through one predicate that gives the same answer every time.

The OXAGEN_LOCAL_DEV flagCopy Anchor Link

pnpm dev sets OXAGEN_LOCAL_DEV=1 for the whole local stack, so you do not normally set it by hand. It marks the process tree as a developer machine, and the auth layer relaxes its deployed-only controls.

Why an explicit flag (and not just NODE_ENV)?Copy Anchor Link

Oxagen builds the auth configuration once, at module load. At that moment, NODE_ENV alone cannot say whether the process is local:

• next dev sets NODE_ENV=development slightly late, so the auth module could read production during early boot and bake in requireEmailVerification: true. That intermittently returned 403 EMAIL_NOT_VERIFIED on local sign-in until an unrelated recompile re-evaluated the module.
• tsx-run services (apps/api, apps/mcp) never set NODE_ENV at all.

The explicit OXAGEN_LOCAL_DEV flag removes that race. Every process in the stack detects local mode the same way.

What "local" relaxesCopy Anchor Link

When Oxagen resolves to a local or development environment, it:

• skips mandatory email verification (you sign up and sign in immediately)
• does not require the OAuth-token-encryption master key
• relaxes cookie hardening

Deployment boundaryCopy Anchor Link

resolveIsLocalEnv in packages/auth/src/local-env.ts evaluates these signals:

The VERCEL check only protects the first and last branches. It does not identify AWS deployments, and it does not guard the NODE_ENV branches. Keep these development signals out of deployed environments. An incorrect value can disable email verification and relax other authentication controls.

When you set it by handCopy Anchor Link

Only when you run a service outside pnpm dev (for example, apps/api on its own with tsx) and want the local relaxations. Export OXAGEN_LOCAL_DEV=1 before you start the process. Never set it in a deployed environment.