Local development

Overview

A handful of controls are meant to be on in deployed environments and off on a developer machine — chiefly mandatory email verification, the mandatory OAuth-token-encryption key, and hardened cookies / rate limits. Oxagen decides which mode it is in through a single, deterministic predicate.

The OXAGEN_LOCAL_DEV flag

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

Why an explicit flag (and not just NODE_ENV)?

The auth configuration is built once, at module load. Deriving "is this local?" from NODE_ENV alone is unreliable at that moment:

• next dev sets NODE_ENV=development slightly late, so the auth module could snapshot production during early boot and bake in requireEmailVerification: true — which 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: local detection is deterministic across every process in the stack.

What "local" relaxes

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

• skips mandatory email verification (sign up and sign in immediately),
• does not require the OAuth-token-encryption master key,
• relaxes cookie and rate-limit hardening for local convenience.

It can never weaken a real deployment

The predicate that honors OXAGEN_LOCAL_DEV is gated on process.env.VERCEL, which is always set on a real Vercel deployment. On a deployed environment the flag is ignored, even if it accidentally leaks into a deployed env file — so it is structurally incapable of relaxing production controls.

A process is treated as local when any of these hold:

When you'd set it manually

Only if you run a service outside pnpm dev (for example, launching apps/api on its own with tsx) and want the local relaxations. In that case export OXAGEN_LOCAL_DEV=1 before starting the process. You never set it in a deployed environment.