Environment Variables

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository. This guide covers where they live in Orbit, how scope and precedence work, marking a value secret, bulk import and export, and the mistakes that produce a variable that is somehow always undefined.

Where They Live

Open your project in Orbit and click the Env vars tab, at /orbit/<project-id>/env-vars.

The page is organised into sections:

All environments at the top: project-wide variables, available in every build.
A collapsible section per environment (Production, Staging, and any previews) holding that environment's overrides.

Above the list there is a search box and a Secrets only filter, which are the fast way through a long list.

How Scope Works

Scope	What it affects
All environments (project-wide)	Injected into every build of this project
Environment-level override	Applies only to that one environment, and wins over the project-wide value with the same key

The subtitle on the page states the rule plainly: project-wide variables are available in every build, and environment-level overrides take precedence.

A typical setup is a project-wide DATABASE_URL pointing at a test database, with a production-level override pointing at the real one. Production builds get the real database, everything else gets the test one, and nothing you add later accidentally leaks the production credentials into a preview.

There is also an Available in control on project-wide variables, letting you exclude particular environment types (production, staging, preview) from a variable that is otherwise project-wide.

Full detail on per-environment scoping, including the security reasoning, is in Setting Environment Variables Per Environment.

A project-wide variable is injected into branch preview builds, and preview URLs are publicly reachable by anyone with the link. Production database credentials, live payment keys and admin tokens must be scoped to production only. This is the single most consequential thing to get right on this page.

Adding a Variable

Scroll to the Add variable form at the bottom of the Env vars tab.
Enter the KEY, for example NEXT_PUBLIC_API_URL.
Enter the value.
Choose a Scope: All environments (project-wide), or a specific environment override.
If you chose project-wide, use the Available in buttons to deselect any environment types this variable should not reach.
Tick Mark as secret for anything sensitive.
Click Add.

The form tells you what it is about to do before you commit: an environment override shows a notice saying it will apply only to that environment's builds, and a restricted project-wide variable shows which environment types it will be injected into.

When Changes Take Effect

Adding, editing or deleting a variable does not change the deployment that is currently live. Variables are injected when a build runs, so the change applies from the next deployment onwards. Redeploy after changing anything your app depends on.

Orbit is explicit about this. Open a deployment's detail page and, if the configuration has changed since it was built, you get an Environment variables updated since this deployment notice telling you the change will not take effect until you redeploy.

Secrets

Tick Mark as secret for anything you would not paste into a chat: API keys, database passwords, tokens, signing keys.

Secret values are masked in the panel and carry a secret badge. Non-secret values show a (plain) marker.

A secret's value cannot be read back after it is saved, not by you and not by anyone else in the panel. You can replace it (click the edit icon, type a new value, save) but you cannot reveal it. Keep your own copy in a password manager before you save it here.

Orbit also tracks how long a value has been in place and shows an age badge on older variables, with a hint suggesting a rotation. That is a nudge, not an enforcement.

Editing and Deleting

Click the edit icon next to a variable to change its value. Click Delete to remove it, and confirm: the dialogue warns that builds depending on it will break, which is the accurate description of what happens on the next deploy.

Bulk Import and Export

Two buttons at the top of the tab handle bulk work.

Import .env opens a paste box. Paste the contents of a .env file, choose a scope, and Orbit tells you how many variables it detected and how many it will mark as secret. It flags keys automatically based on their names, so anything containing SECRET, TOKEN, KEY, PASSWORD and similar is marked secret before import. There is an Overwrite existing variables with the same key option, off by default.

Download .env produces a template containing the variable names only, with no values. It is meant to be shared with a teammate who then fills in their own values, not used as a backup.

Downloading a .env template never includes values, including for non-secret variables. There is no way to export values from Orbit. If you need a copy of a value, take it from wherever you originally generated it.

Copying Variables Between Environments

The Copy variables between environments panel copies a whole set from one scope to another. Choose a From (project-level or a specific environment) and a To, optionally tick Overwrite variables that already exist in the target, and click Preview to see exactly how many will be added, updated and skipped before you commit.

There is also an Env sync check page that compares production and staging key by key and reports what is only in one, what differs, and what matches. It is the right tool for "why does staging work and production not".

Sharing Variables Across Projects

If several projects need the same credential, use an env group rather than copying it into each project. Go to Orbit, then Env groups, create a group, add variables to it, and link the projects that need them.

Group variables are injected at build time, and project-level and environment-level variables take precedence over group variables. You can have up to 20 groups on an account.

Framework Notes

Which variables reach the browser is decided by your framework, not by Orbit. Orbit injects everything in scope; the framework decides what to expose.

Next.js: keys prefixed NEXT_PUBLIC_ are inlined into the browser bundle at build time. Everything else stays server-side.
Vite: keys prefixed VITE_ are exposed to the browser. Everything else is build-time only.
Node.js apps: everything in scope is on process.env during the build, and at runtime when Server mode is on.

Never mark a value secret and then also prefix it NEXT_PUBLIC_ or VITE_. The secret flag only controls whether the panel shows you the value; the prefix controls whether your framework ships it to every visitor's browser. The prefix wins.

Checking What a Build Actually Received

Every deployment detail page lists the environment variable keys that were injected at build time, and diffs them against your current configuration: added, changed, removed and unchanged. Teal keys came from an environment-specific override, grey ones from project level. Values are never stored or shown, but hovering a key gives a SHA-256 fingerprint, which is enough to confirm two environments hold the same value without revealing it.

This is the definitive answer to "is my variable actually reaching the build". Check it before you change anything else.

Troubleshooting

The variable is undefined at runtime. Check the deployment postdates the change, then check the scope covers this environment, then check the framework prefix rules above. In that order.

It works in production but not in a preview. The variable is scoped production-only, or a project-wide variable has preview deselected under Available in. That is usually deliberate.

It works locally but not in the build. Your local .env file is not in the repository, and should not be. Import it with Import .env and pick the right scope.

Staging is missing everything production has. Turn on Inherit production env vars in Settings, under Staging: environment variables, or use Copy variables between environments.