Development and staging that never touch production
Every environment is a tenant of its own: its own database, users, keys, webhooks and senders. Build and test there, then promote the configuration that works. Environments are rolling out to organizations: yours has them once the console shows Environments under Settings > Organization.
From one command to a promoted change
Production is where your customers are. Development and Staging are where you get it right first.
Add an environment
From the console, or with buildbase env create. It gets its own database, users, keys and sign-in client, ready on first use. Production is your organization itself, as it always was.
Point your app at it
The CLI writes NEXT_PUBLIC_BUILDBASE_ENVIRONMENT and the client secret to .env.local. The SDK reads the key; leave it unset and the app talks to production.
Promote what works
Build templates, workflows and plans there, read the diff, and promote them. They arrive in production as drafts until you publish them, and no user or record ever moves.
Your terminal, your code, one option
The CLI sets the app up; the SDK sends every request to the environment it names, and to production when it names none. Both need @buildbase/sdk 1.0.0 or later: an older SDK ignores the option and talks to production.
npx buildbase login
npx buildbase init --dev # wire to Development
npx buildbase env create Staging
npx buildbase env diff Staging # what would change
npx buildbase env push Staging # promote it<SaaSOSProvider
serverUrl={process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL}
version="v1"
orgId={process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID}
// unset is production
environment={process.env.NEXT_PUBLIC_BUILDBASE_ENVIRONMENT}
>
<App />
</SaaSOSProvider>import { environmentId } from '@buildbase/sdk';
// <orgId>-<key> in an environment, the org id itself in production
const orgId = environmentId(
process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!,
process.env.NEXT_PUBLIC_BUILDBASE_ENVIRONMENT
);
await fetch(`${serverUrl}/api/v1/auth/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ code, orgId, clientId, clientSecret }),
});The CLI commands, the environment option and environmentId() need @buildbase/sdk 1.0.0 or later. Everything in the console below works today. On an older SDK, your server can reach an environment by sending your org id and the environment's key, joined by a hyphen, as the org id.
What every environment gets
Its own data and credentials, everything working on first use, and a way to move configuration without moving data.
Nothing shared with production
Each environment is a tenant of its own. What happens in one never reaches another.
- Its own database: users, sessions, workspaces, audience, lists, tags, email history, workflow runs and files
- Its own credentials: API keys, client secrets, webhook endpoints and their signing secrets, senders and Stripe keys
- Its own background work: every queued job, scheduled send, webhook delivery and cache carries its own key
- One team: the same members in every environment, and you choose which environments each member may enter
Ready the moment it exists
Sign-in, mail and test accounts work before you configure anything.
- Google and GitHub sign-in with no OAuth app of your own
- Mail through a platform sender to your team's addresses only, every message kept in the environment's inbox in the console, links and codes included
- Test mode: an address ending in +test is never sent mail, and every code it asks for is 424242, so automated tests sign up and sign in with no mailbox
- Redirects to localhost and http:// webhook endpoints are accepted, and Stripe takes test keys only
- The hosted sign-in pages carry a ribbon naming the environment
From your terminal and your code
One command connects your app to an environment, and one setting tells the SDK which environment to use.
- buildbase init --dev wires an app to your Development environment, client secret included
- buildbase env create <name> adds an environment and points the app's .env.local at it
- The SDK's environment option takes the environment's key; leave it unset for production. It is never guessed from NODE_ENV
- The SDK's MCP server lets a coding agent list your environments and create one
Configuration moves, data stays
Build a template or a workflow in Development and promote it when it is right.
- See what would change, item by item, before anything moves: unsubscribe groups, email templates, workflows, plans and plan groups
- Promote from the console's Changes tab or with buildbase env push: a workflow lands as a draft, a plan as a new draft version whose prices are made when it is published
- Bring production's configuration into an environment the same way, with buildbase env pull
- Users, records, history, secrets, keys and webhook endpoints are never copied
Priced by how many, never by use
Your plan sets how many environments you can have besides production.
- Never billed: an environment's users, usage and storage do not count toward your plan's quotas or monthly active users
- Rename an environment without changing its key, its database or anything deployed
- Archive one to free its place for another
Run it from the console
Add, enter, test and promote without leaving the dashboard, and see what production still needs before it goes live.
Always know where you are
The sidebar always shows which environment you're in, by name, in green for production and amber for the rest. Switch from the same menu. Owners and admins add and manage environments there too.
Connect an app in one copy
Each environment's dashboard shows the org id, key and sign-in client your app needs, ready to copy. The client is made the first time you need it, already allowed to send people back to localhost. Its secret is shown once, and Rotate gives you a new one.
Every message in an inbox
Every email an environment sends lands in its Inbox in the console, links and codes included. And an address ending in +test signs in with the code 424242, so you can test sign-up without a real mailbox.
Choose who gets in
Your team is the same in every environment. Give each person all of them, a chosen few, or production only. The owner can always get in.
Compare, then promote
The Changes page lists what's different between two environments, item by item. Pick the rows you want and copy them across, in either direction. Every move is recorded in both environments' audit logs.
Reset or archive
Reset wipes an environment and starts it again empty, with the same key. Archive retires it and frees up its slot. Both ask you to type its name first, so nobody does it by accident.
A readiness check for production
Once you build in environments, production's dashboard warns you about what would break at launch: Stripe test keys, sign-in clients that still send people back to localhost, or no email sender set up. Each warning links to the fix.
Limits of its own
Every development and staging environment gets the same usage allowance, whatever your plan, shown on its dashboard. Nothing you use there counts against production.
Your plan sets how many
Each plan includes a number of environments besides production, and none of them is billed: their users, usage and storage never count toward your plan. Your subscription, custom domains and live Stripe keys stay in production.
Compare plansFrequently Asked Questions
Can my organization add an environment today?
Environments are rolling out to organizations: yours has them once the console shows Environments under Settings > Organization. Until then, buildbase env create is refused too, and your app keeps running in production as it always has.
Is an environment a copy of production?
No. Each environment starts empty and keeps its own database, users, keys, webhooks and senders. Production is your organization itself, as it always was. Configuration moves between them when you promote it; users and data never do.
How does my app choose an environment?
With the SDK's environment option, set from NEXT_PUBLIC_BUILDBASE_ENVIRONMENT: the environment's key from the console, or nothing for production. buildbase env create and buildbase init --dev write it to .env.local for you. It is never guessed from NODE_ENV (whether your app runs in development or production mode), so a preview deployment cannot reach production by accident. The option and the commands need @buildbase/sdk 1.0.0 or later: an older SDK ignores the option without an error and sends every request to production.
Can my automated tests sign in without a mailbox?
Yes, in any environment but production. In test mode, an address ending in +test is never sent mail, and every code it asks for is 424242. Every other message the environment sends is kept in its inbox in the console.
What moves when I promote?
Unsubscribe groups, email templates, workflows, plans and plan groups, after a diff that shows each change. A workflow arrives as a draft and a plan as a new draft version, so nothing goes live in production until you publish it there. Users, records, history, secrets, keys and webhook endpoints never move.
Does an environment cost anything?
Your plan sets how many environments you can have besides production. They are never billed: an environment's users, usage and storage do not count toward your plan's quotas or monthly active users.
What stays in production only?
Your subscription and invoices, custom sign-in and sending domains, and live Stripe keys. Your team is shared: the same members in every environment, with a choice of which environments each member may enter.
Can I start an environment over?
Yes. Reset wipes everything in it, including users, content, settings and keys, and starts it again empty with the same key. Archive deletes it and retires its key for good, so it no longer counts toward your plan's environments. Both ask you to type its name first, and neither touches production.
How do I know production is ready to go live?
Once you build in environments, production's dashboard shows a go-live checklist. It flags Stripe test keys, sign-in settings that still send people back to localhost (your own computer), and a missing email sender. It is advice only: each line links to its setting, and production keeps working either way.
Build in Development, ship to production
Add a Development environment in the console, or run buildbase init --dev with SDK 1.0.0 or later. Sign-in and email work there from the start, and production stays untouched.