Environments
Every project starts with one environment, production, which is your live
app. On a Business plan you can create others — staging, qa, development,
any name you like — to try changes on a copy before they reach your users.
development is an ordinary name. If your project already had a development
environment from before, it's now listed, reset and deleted like any other.
What an environment is
A created environment is a separate copy of your app's backend, which runs once you publish to it. Each one has its own:
- Database — a copy of production's database, schema and data, taken when the environment is created or reset. This copies real production rows, including your end users' accounts, so treat an environment's data with the same care as production's. See Environments: a database each.
- Variables — its own scope. It inherits your project-wide values unless you override one for it. See Variables for one environment.
- File storage — its own, starting empty. See File storage.
- Sign-in sessions — signed with a session key of its own.
- Address —
<your project's address>--<name>on Berrybell's preview domain, for examplemy-shop--staging. The card shows the full address. Nothing is served there until you publish to the environment, and only your workspace can open it. See Where each environment is served. Where available, it can also have custom domains of its own (see Custom domains).
What isn't separate is the code. Every environment is published from the same project files — the ones the preview is running when you press Publish — and there is no per-environment code branch. A change you try on staging reaches production when you publish those same files to production.
Differences from production
An environment behaves like production except for these:
- Payments run in Stripe sandbox, on the project's one sandbox account, even when production takes real payments. With no sandbox account connected, checkout fails with "The project has no sandbox Stripe account connected, so this environment can't create products or take test payments. Select production in the top bar, then create or connect a sandbox account." It never falls back to live. One exception: an environment published before it had its own store key keeps the project's key until you publish it again, and while it does, a checkout its server starts runs in production's Stripe mode. See Only production takes real payments.
- Live Stripe keys you store yourself never reach it. See Live Stripe keys reach production only.
- Sign-in email — address confirmations and password-reset links — stays off until you press Send email from this environment in Cloud → Email and then publish to the environment. Until then, "Forgot password" fails there. See Environments and the preview.
- App email — once notifications to you or template emails are on, there's nothing to turn on for the environment: it gets a token of its own the next time you publish to it. They reach only your own team. Notifications go to owners and admins, never to extra addresses, and a template email to anyone outside the workspace is held, not sent. See Outside production.
- Google and single sign-on show Production only until you choose Allow in this environment, which takes effect the next time you publish to that environment. See Sign-in in other environments.
- Scheduled jobs never run in it. They are production-only: with another environment selected, Schedules says so (see The selected environment). They need a Pro or Business plan; see the FAQ.
- Backups are always production's. An environment has none of its own — reset it to get a fresh copy instead.
- Traffic analytics count production only.
Requirements and limits
- A Business plan. A subscription still on trial counts. Without one, the Environments card reads "Environments require a Business plan — view plans.", and creating one is refused with "Multiple environments require a Business plan. Upgrade to create environments besides production."
- The database turned on and ready. Until it is, the card is replaced by "Each environment starts as a copy of your database, so turn on the database first." and an Open Database settings button.
- Currently up to two environments besides production. The card shows the count — "1 of 2 environments" — and that count is the source of truth if the limit changes. At the limit, Create is disabled with "Business projects can have 2 environments besides production. Delete one you no longer use." An environment that failed to set up still counts.
- The Editor role or higher to create, reset, delete or switch environments.
If your workspace leaves the Business plan, the environments you already have keep working: you can still reset them, publish to them and delete them. Only creating a new one is refused.
Creating one
- Open Project settings → Cloud.
- In the Environments card — "Environments — each gets its own database
branch, variables and URL." — type a name. The field's placeholder is
staging. - Check the line under the field. It shows "Will be served from" followed by the address, or says why the name can't be used.
- Press Create.
The new row reads Preparing (branching from production)… until the environment is ready. The card keeps checking on its own.
A name has to be:
- lowercase letters, numbers and single hyphens, up to 20 characters;
- not a reserved name —
production,preview,sandbox,default,www,api,admin,assets,static,cdnormail("That name is reserved."); - short enough that
<project address>--<name>fits in 63 characters, so a long project address leaves less room; - not one that would give the same address as another project's;
- not already used in this project.
If your project's address starts with v- or contains --, no name will work
until you change the address: press Publish and use the pencil beside the
address (see The address).
Environment addresses are built from the project's address, so changing it also
changes the address each environment publishes to.
Creating an environment moves nothing: the preview and the AI stay on production until you switch.
The selected environment
Once a ready environment besides production exists, a switch appears in the top bar, beside the project name. Its menu is headed "The preview and your changes use", marks production as live app, and ends with Manage environments, which opens the Cloud overview.
The selection belongs to the project, not to you. Switching changes it in every tab and for every teammate, and they see a notice such as "Sam switched this project to staging. The preview and new changes use it now."
What follows the selection:
- the automatic preview's database and file storage, and the dev server's database (the dev server has no file storage);
- the changes you send in the chat, and AI edits made in select mode;
- the AI's database and payments tools;
- Cloud → Database, Storage, Domains, Auth (sign-in address, Google, SSO and users), Email, Payments and Variables, and the usage on the Cloud overview.
As the overview puts it: "Cloud, the preview and the changes you send use the environment chosen in the top bar, beside the project name. Publishing asks you to choose each time."
Two Cloud pages are exceptions. With another environment selected, Schedules shows "Schedules only run in production" and a Switch environment button. On Auth, turning sign-in on or off applies to the whole project and the checks at the top of the page describe production; the page says so.
What doesn't follow the selection: Publish, which asks every time, Analytics, Security and SEO & GEO.
Switching has a few limits:
- It's blocked while a chat run is streaming ("Wait for the chat run to finish before switching.") or while a change holds the project ("A change is running on this project; switch when it finishes").
- With the preview running, the pane shows "Switching the preview to staging…" while it moves over.
- The menu lists only ready environments, so one that is being set up or reset isn't offered until it's ready. (Choosing it from an out-of-date menu gives "staging is being set up or reset. Select it when it's ready.")
Production asks first
This applies only to a project with other environments, and the Environments card says so: "Changes go to the environment you select. Production asks first." A project with only production is never asked.
- Selecting production opens Switch to production? — "The preview, the dev server and the changes you send all use your live app's data until you switch again." — with Cancel and Switch to production.
- Sending a chat message while production is selected but not yet confirmed — for example straight after you create your first environment — opens Send this change to production? with Cancel, a button for each other environment that is ready (Use staging), and Send to production. Use staging switches the project and sends the message there. Once you've confirmed production, later messages don't ask again until the selection changes.
- Three writes from Cloud pages ask every time, and the answer is never remembered: Run this SQL on production? (Run on production), Restore production? (Restore production) and Turn on sign-in for production? (Turn on for production), which adds the sign-in tables to production's database only. Other environments get them when you reset them.
- AI changes to production through its Berrybell Cloud or payments tools always show an approval card, whatever the permission is set to — unless it's Never allow, which still blocks them. Reads aren't covered by this rule; they follow their permission as usual. The card's preview starts "On production:", and only your answer to that card lets that call through: no earlier approval covers it. Choosing Always allow on it changes the permission, but the next change to production still asks. See Changes to production.
While production is selected, the chat composer shows "Changes go to production" and the preview pane shows Preview is using production data.
While production is selected, the dev server's database connection is production's. Code the AI runs inside the project — a script, a seed, its own database client — can change production data without any tool prompt. The approval cards above cover the AI's Berrybell Cloud and payments tools, not everything that runs in the project. Select another environment for work you want kept away from live data.
Database changes don't travel with a publish
The AI and the Cloud pages change an environment's database only while that environment is selected, and nothing applies a schema change when you publish. Publishing ships code, not database changes.
When the AI changes the schema on staging, it records the change as a migration file (see Schema changes and migration files) and applies it to staging's database only. Before you publish code that needs the change to production:
- Switch to production in the top bar.
- Ask the AI to apply the pending migrations there.
- Publish to production.
Publish first, and production runs the new code against the old schema.
To bring an environment back in line with production instead, reset it for a fresh copy.
Publishing to an environment
On a project with more than one ready environment, Publish asks where every time. Choose where to publish lists production and each ready environment, nothing is preselected, and the button names the target — Publish to staging. See Choosing an environment.
Each publish uses that environment's own database, variables, file storage and domains, and ships the project files as they are at that moment. An environment that is still being set up or reset can't be published to.
Resetting
Reset replaces an environment's database with a fresh copy of production. It asks first: "Reset "staging" from production? Data and schema changes made only in staging will be discarded." The button is enabled only while the environment is ready.
- The environment gets an exact copy of production, including the record of which migrations have been applied. Migrations applied only in that environment are undone; their files stay in your code.
- Its variables, storage files and domains are kept.
- Reset is also how an environment gets the sign-in tables after you turn sign-in on.
- While the reset runs, the row reads Preparing (branching from production)… again and you can't publish to the environment. If it's the selected environment, the preview has no database and changes can't be sent until the reset finishes.
Deleting
The trash icon on an environment's row opens Delete the staging environment?. When you delete it:
- Its database — its data, its schema changes and its compute — is destroyed and can't be recovered. Production is untouched.
- Its variables are deleted too, including values you set only for that environment.
- Its past deployments stay in the project's history.
- Its address stops being a publish target, but anything already published there keeps serving its last build.
- Its storage files are scheduled for deletion after a grace period (7 days by default). Creating an environment with the same name later gives it new, empty storage. The dialog doesn't mention storage.
Delete is refused while the environment has custom domains: "staging still has a custom domain, staging.yourbrand.com. Remove its domain first, then delete the environment." In place of Delete, the dialog offers Open Domains for staging, which selects staging and opens Cloud → Domains so you can remove it.
If you delete the selected environment, the preview says "staging was deleted, so the preview has no database. Choose an environment." and the composer says "staging was deleted. Choose an environment to send changes." Pick another environment in the top bar.
Production can't be reset or deleted.
Custom domains
A custom domain belongs to exactly one environment, so staging needs a domain of
its own — staging.yourbrand.com, say — rather than sharing production's. See
Domains and environments,
which also notes that domains on environments other than production aren't
available everywhere yet.
Usage and costs
Each environment draws on your workspace's hosting budget the same way production does: its database compute and storage, the requests and CPU time of its published app, and its file storage. On a project with environments, Usage this billing cycle on the Cloud overview splits the figures:
- Used by staging — the environment Cloud is showing, including its database's storage while it sleeps.
- Automatic preview — the preview that updates while you build.
Every cost is on one environment's card; anything that can't be tied to a specific environment counts as production's. Usage is collected every hour and can be a few hours behind. See Usage per environment.
When something says no
| Message | What it means |
|---|---|
| "This project is now on staging. Check it and send again." | A teammate switched the project before your message went. It wasn't sent, and it's back in the composer. |
| "Reload Berrybell to choose an environment." | The tab is out of date. Reload it. |
| "The preview wasn't deployed because …" | The selected environment was deleted or isn't ready, so no automatic preview build was made. Choose a ready environment. |
| "staging failed to set up…" | Creating or resetting it failed, and its row shows the error with only Delete available. Delete it and create it again. The message mentions retrying, but there's no retry button yet. |
| "Environment "staging" is provisioning — wait for it to be ready, then publish." | You tried to publish to an environment that is still being set up or reset. |