Variables & secrets
When your app needs an API key, a webhook URL or a feature switch, it goes here. Open your project settings, then Cloud → Variables.
The Variables page lists your own variables. It doesn't list the values Berrybell sets for its own features — see Values Berrybell sets for you. On a project with environments, the page follows the environment selected in the top bar: production shows the project-wide list described below, and any other environment shows what that environment receives.
Public values and secrets
Each entry is one of two kinds, and the difference matters:
- Public — stored and shown as plain text, and shipped to the browser along with your app (unless you set it to server, below), where anyone who uses it can see it. Fine for a public API base URL or a switch. Never put a key here.
- Secret — encrypted at rest and shown only as dots. The Variables page never shows the value again, so if you forget one, replace it. Secrets that reach the agent sandbox are readable by code running there — see What the AI can see.
The form's menus show these as public and secret. Each entry also says where it is injected: client (built into the app), server (the server-side environment only), or both. A new entry starts as secret / server. Choosing secret sets it to server; choosing public sets it to both.
A secret is never written into the client bundle, so a secret set to client reaches neither the browser nor the server — your app doesn't get it at all. Use server or both for a secret.
Add and Save stay disabled until both the key and the value are filled in. Editing a secret never shows its current value: the field reads Enter a new value to replace, so saving any change to a secret means typing its value again.
Naming and size rules
Keys are UPPER_SNAKE_CASE — a letter or underscore first, then letters, digits
and underscores, up to 128 characters. The field uppercases what you type.
Values can be up to 8,192 characters.
Where a value applies
By default a variable applies everywhere. The scope menu in the form lets you give one place its own value instead:
- All environments — the project-wide value. The hint reads "Used everywhere this app runs."
- Agent sandbox — where the AI works and the dev server runs.
- Preview deploy — the automatic preview deploy.
- Published app — production only.
- One entry per ready environment you created, by name — staging, for example.
Anything but All environments is an override, and the hint says so: "Used only on the published app, overriding the project-wide value.", or "Used only on the staging environment, overriding the project-wide value." for an environment you created.
In the list, an override sits next to the project-wide value it shadows, with a
badge showing its scope as stored: sandbox, preview, production, or the
environment's name. While you're editing an entry, the key and the scope are
locked, so renaming can't quietly create a second row for the same name. To move
a value to another scope, delete it and add it again.
When a key has more than one value, this is the one each place uses:
- The published app uses the Published app value if there is one, otherwise the project-wide value.
- An environment you created uses its own value, otherwise the project-wide value.
- The agent sandbox and the preview use their own value (Agent sandbox or Preview deploy), then the value set for the environment selected in the top bar, then the project-wide value.
So the agent sandbox and the preview never use a Published app value, the agent sandbox doesn't use a Preview deploy value, and the preview doesn't use an Agent sandbox value.
Deleting an environment deletes every value scoped to it. Environment names
can't be default, sandbox, preview or production, so an environment can't
take over one of the built-in scopes.
Variables for one environment
On a project with environments (creating one needs a Business plan), selecting one other than production in the top bar changes the page. It shows what that environment gets when you publish to it, one row per key, under "Your variables, as this environment receives them when you publish to it."
Each row has a badge:
- Inherited — the environment uses the project-wide value.
- Overridden here — the environment has its own value, used instead of the project-wide one.
- Not sent here — the environment doesn't receive this variable. The reason is shown under the row: for example, a key that has no value yet (such as an Expert Assist key you haven't supplied), or a live Stripe key.
What you can do with a row:
- Override here, on an Inherited or Not sent here row, adds a value for this environment only. The key stays fixed.
- Edit and Remove override, on an Overridden here row, change or delete this environment's own value. After Remove override, the key falls back to the project-wide value, or leaves this environment if there isn't one.
- Add variable adds a value for this environment. The form has no scope menu; it reads "Used only in this environment. Other environments aren't affected."
Changes take effect the next time you publish to that environment. A value set for an environment also reaches the preview and the agent sandbox while that environment is selected.
If the list can't load, the error offers Try again. If the selected environment has been deleted or isn't ready, the page shows production's list instead. With nothing set, the page reads "This environment has no variables yet." Viewers see the rows locked.
Live Stripe keys reach production only
A value that starts with sk_live_, rk_live_ or pk_live_ and is set for
All environments goes to the published app only. Environments you created,
the preview and the agent sandbox never receive it. In an environment's view it
shows Not sent here with "Only production can use a live payment key, so add
a test key for this environment instead." Use Override here to give that
environment a test key.
A variable whose name contains STRIPE and whose value doesn't show its mode —
a webhook signing secret (whsec_…) looks the same in both — is treated as live
when it's inherited from All environments: "Berrybell can't tell whether the
project-wide payment key is a live one, so add a test key for this environment
instead." Setting such a value for that environment, or for Agent sandbox
or Preview deploy, gets it through.
Saving a live key as an environment's own value is refused, with your key's name in the message — for example "STRIPE_SECRET_KEY holds a live-mode payment key, and only production can use one. Set a test key for this environment instead."
- This applies to every project, including one with only production: a live key set for All environments doesn't reach the preview, so checkouts you try in the preview need test keys.
- A live key saved for Agent sandbox or Preview deploy is accepted but never delivered. Save a test key there instead.
- Berrybell's own store keys (
pk_store_…) aren't affected. See Stripe payments.
Values Berrybell sets for you
Some features give your app the values they need: the Cloud database (the connection string and session key), sign-in for your app's users (the sign-in address and sign-in settings), payments (the store keys), app email (its send address and token) and integrations you connect (their keys). Every publish delivers them, but they aren't listed on the Variables page, and you can't add, edit, delete or override them. Trying gives a message such as "SESSION_SECRET" is managed by Berrybell and can't be edited here. To remove them, turn the feature off. A managed key is locked at every scope, so you can't add a per-environment override for one either.
These names are refused at every scope, even while their feature is off:
SESSION_SECRET, AUTH_BASE_URL, AUTH_EMAIL_SEND_URL, AUTH_EMAIL_TOKEN,
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRET, AUTH_SSO_BROKER_URL,
AUTH_SSO_CLIENT_ID, APP_EMAIL_SEND_URL, APP_EMAIL_TOKEN,
VITE_BERRYBELL_STORE_KEY, BERRYBELL_STORE_ADMIN_TOKEN,
BERRYBELL_WEBHOOK_SECRET and BERRYBELL_CRON_SECRET.
Environments you created, the preview and the agent sandbox get their own session key, store keys, sign-in address and app email token rather than production's.
Three cases work differently:
- Expert Assist keys are listed. A key an Expert Assist build asked you for appears read-only, with a lock and an assist tag. You can't change its value here.
- Bringing your own Postgres. If you add
DATABASE_URLfor All environments yourself, Berrybell also creates aSESSION_SECRETfor your app. It isn't listed. - Generated values aren't managed. A value Berrybell generates when a
project is created — such as the Booking system template's
ADMIN_PASSWORD— is an ordinary secret. Replace or delete it like any other. See A password shown exactly once.
The agent sandbox and the preview get a DATABASE_URL for the database of the
environment selected in the top bar — production's, on a project with only
production. If the selected environment has been deleted or isn't ready, they
get no DATABASE_URL at all, never production's. A publish to an environment
you created always uses that environment's own database.
With the Cloud database on, DATABASE_URL is one of the values Berrybell
manages, so you can't override it at any scope.
Reserved names
Berrybell refuses to create a variable called BETTER_AUTH_SECRET,
BETTER_AUTH_SECRETS or AUTH_SECRET. Those names would silently replace the key
that signs every session your app has ever issued, invalidating all of them.
The message suggests SESSION_SECRET instead, but you don't add that yourself:
Berrybell creates it, your app's session signing key, when your app has a
database, and you can't set it. The check runs again at deploy time, so there's
no way around it.
A variable called NODE_ENV has no effect on a published app: deployed apps
always run with NODE_ENV=production.
What the AI can see
The assistant is told the names of the variables its sandbox receives, and the values of public ones — not secret values. It's instructed to reference secrets by name and never inline one into browser code.
That doesn't keep secrets away from code the AI runs. Secrets that reach the agent sandbox are written to a file there for your dev server, so code the AI runs in the sandbox can read them. The Google client secret and the sign-in email token are left out of that file. A publish is built on the same machine, though: the server values of the app being published — those two, and values set only for Published app, included — are written there while the build runs, and deleted as soon as the build has read them.
Inside the agent sandbox and the preview:
- Google sign-in and sign-in email don't work. They work on the published app, and in an environment once you set them up there — see Sign-in in other environments.
- Sessions are signed with their own key, not production's.
- App email uses its own token, which can email only your own team. See Outside production.
- Live Stripe keys aren't passed.
Changes take effect on the next publish
Editing a variable doesn't change your live app straight away. The published app picks up the change the next time you publish, and an environment you created the next time you publish to that environment. The agent sandbox and the preview pick it up when the preview next rebuilds — normally after the AI's next change.
Permissions
Anyone with access to the workspace can view the list. Adding, editing and deleting entries needs the Editor role or above. In an environment's view, Override here, Edit and Remove override appear only for Editors and above.