Environment variables

Agent Zero reads credentials and deployment policy exclusively from the environment. Endpoint URLs and credentials can never be named or embedded in .agent-zero.yml, so untrusted repository policy cannot redirect a secret.

One env file per process

Each process reads exactly one .env, and that file sits next to the process that reads it. Nothing is shared implicitly: a file is loaded only by the process it belongs to, by that process's own tooling.

Each has a checked-in .env.example next to it; copy the ones you need:

cp .env.example .env
cp apps/dashboard/.env.example apps/dashboard/.env
cp apps/docs/.env.example apps/docs/.env
cp packages/database/.env.example packages/database/.env

Every file is optional. A deployment that sets real environment variables ships no .env at all, and real variables always win over the file.

A variable two processes both read is written in both files on purpose, rather than one process inheriting the other's configuration:

• DATABASE_URL is read by the dashboard (the only process that opens the database) and by drizzle-kit when migrating. Point both at the same database — drizzle.config.ts and the server resolve it through the same function precisely so migrations cannot target one store while the dashboard opens another.
• The model-provider keys are read by the CLI and, when the hosted control plane executes runs, by the dashboard.

server/auth.config.ts resolves DATABASE_URL at module load, so a dashboard started without it fails on the first request (missing required environment variable: DATABASE_URL) rather than degrading quietly.

Model providers

Each provider reads only its documented variable. See Model providers for the full matrix.

Control plane

The control-plane API (/rpc/** and /api/v1/**) fails closed: without AGENT_ZERO_CONTROL_PLANE_TOKENS every mutation is rejected while reads stay open.

See Protect endpoints for how these are enforced.

Webhooks

POST /webhooks/github fails closed (503, nothing ingested) until both variables are set.

Status publishing reads one fixed variable per provider (GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_CLOUD_TOKEN, BITBUCKET_DATA_CENTER_TOKEN, GITEA_TOKEN) — see Source-control providers.

Authentication

Registration and GitHub OAuth are off until you turn them on, so a fresh deployment cannot be signed up for by a stranger.

Hosted infrastructure

Cloud-managed deployments only. @better-auth/infra's sentinel() and dash() plugins are registered only when all three are set; a self-hosted install leaves them empty and gets neither.

Mail

console logs instead of delivering and is the default when neither MAIL_PROVIDER nor RESEND_API_KEY is configured, so an unconfigured deployment cannot silently attempt real delivery. If MAIL_PROVIDER is absent, a Resend credential selects Resend automatically; an explicit provider always wins.

See Mails.

Dashboard

Deployment target

Build-time only: these pick the deployment preset the dashboard build emits, and with it the KV driver its task history resolves. Unset means the self-hosted node-server bundle in .output/.

Each variable is matched against its own vocabulary and nothing else: a value ViteHub would refuse to build under — vercel-edge or a bare node in NITRO_PRESET, say — is rejected up front rather than resolved to the neighbouring target.

See Deployment.

Build metadata

Every Nuxt app resolves what build it is — version, commit, branch, deploy channel, deploy URL — and publishes it under runtimeConfig.public.buildInfo, read with useBuildInfo(). The resolution lives in packages/build-env and runs in two passes.

The first pass runs during the build. It asks the hosting provider first and the checkout second: a provider knows the branch a detached CI checkout cannot name, and knows whether the deploy is production. VERCEL_GIT_COMMIT_SHA and friends on Vercel, COMMIT_REF and CONTEXT on Netlify, CF_PAGES_COMMIT_SHA on Cloudflare Pages, GITHUB_SHA on a GitHub Actions runner. None of these are set by you; they are set by the platform, and are listed in turbo.jsonc so a build never restores a cached bundle that reports a different commit.

The second pass runs in the deployed server, and is what every target that is not Vercel needs. A container image built in CI has none of the platform variables in scope while it is being built, so its first pass resolves what git can tell it and leaves the rest as unknown. Those fields — and only those — are completed when the server starts, from the environment the host actually runs it in. A field the build resolved is never overwritten: the commit a bundle was compiled from is a property of the bundle, not of the machine serving the request.

For a deployment on no recognised platform, or one that wants to state outright what it is:

Setting any of them takes precedence over every auto-detected platform, so an operator's answer always wins over an inferred one. AGENT_ZERO_BUILD_ENV is the field detection can never work out on its own: a self-hosted staging deployment is a preview in every way that matters to the people looking at it, and nothing about a plain node .output/server/index.mjs says so.

Individual fields can also be overridden through Nuxt's own public runtime config channel — NUXT_PUBLIC_BUILD_INFO_COMMIT, NUXT_PUBLIC_BUILD_INFO_BRANCH, and so on — which applies before the server's own pass and needs no rebuild. There is no _SHORT_COMMIT variant: the dashboard derives the abbreviated form from commit wherever it is displayed, rather than declaring it as its own field that could drift from the commit it abbreviates.

A prerendered route has no server left to ask, so on apps/marketing the second pass runs while the page is prerendered rather than while it is served. On Vercel that changes nothing: the build already resolved every field.

Documentation