Secrets & environment
Dev and production variables, per-sandbox overrides, and which credentials stay out of your sandbox.
Your app needs database URLs, API keys, and configuration to run. Set ordinary environment variables on the project rather than copying .env files between threads. Project Settings has two separate maps:
| Setting | Where the values go | Who can read them |
|---|---|---|
| Sandbox variables | Every sandbox's .env, for building and testing your app | Project members can reveal them, because they can read the sandbox; managers can change them |
| Live variables | Your deployed app: worker bindings and public-prefixed values baked into the build | Managers can reveal and change them; they do not reach sandboxes |
Neither map falls back to the other. A plain value your app needs during development and in production must be entered in both places. A Sandbox variable does not become a deploy binding, and a Live variable does not make a local build work. If a key should be usable by an agent but not readable in its sandbox, use the Secrets vault instead.
The server owns .env
The server writes each sandbox's .env wholesale from Sandbox variables and vault placeholders. A hand-edit to .env — yours or an agent's — will disappear on the next sync or boot. Adding a Sandbox variable in Project Settings doesn't erase the others in that map, but the resulting .env file is rebuilt from the current project state, not patched line by line.
For a value that should exist in only one sandbox, use .env.local instead:
| File | Written by | Survives an environment sync | Reaches other threads |
|---|---|---|---|
.env | The server, from Sandbox variables and vault placeholders | No — rewritten from scratch | Yes — every sandbox gets the project values |
.env.local | You or an agent in one sandbox | Yes | No |
Where your app loads .env.local, it can override .env for a throwaway test value or local experiment. It is not part of the project recipe or snapshot; don't rely on it to configure a future thread. See run config & snapshots for what a fresh environment replays.
Restart to pick up new values
An already-running process may still hold the environment it started with. After changing Sandbox variables, update a sandbox's environment if it shows as stale, restart the app, and check the logs. Live variables take effect through the deploy path, not a sandbox restart; see hosting.
What never enters a sandbox
Live variables never flow into a thread's .env. Neither do the real values in the Secrets vault: a vaulted API key or connected-account token is injected only when a request reaches its designated provider host. Website passwords and saved login sessions stay in the isolated login browser's server-managed vault, not in the work sandbox. Read the vault & login browser before choosing where a credential belongs.
GitHub credentials are separate again: the server authenticates git for the project's repository without putting a token in the sandbox. A second repository needs an approved access window. See GitHub & authentication.