Publishing your app
When your app looks right in the preview, publish it to make it available on the web. Publishing is one click: Publish in the top bar opens a popover that shows the site as it stands — where it lives, who can view it, whether it's up to date — with the button that ships it underneath. Nothing has to be set up first.
You don't have to start the preview first
Berrybell builds your app on your project's own preview machine, but the preview doesn't have to be running when you press Publish. If it isn't, pressing Publish starts it and then builds. While the preview isn't up yet, a hint beside the button says what will happen:
- "The preview isn't running. Publishing starts it first, then builds."
- "The preview is still starting. Publishing begins as soon as the project's files are ready."
The build waits for your project's files and dependencies to be in place, not for the preview page to load. If the machine can't be found or started, the publish fails with "The project's VM isn't available to build on — reopen the preview, then publish again."
Two things do still need a running preview: uploading images in Site info, and publishing from the chat.
The Publish popover
Press Publish in the top bar. From top to bottom, the popover shows:
- A status header — whether this environment is published, and whether the live site is up to date. See The status header.
- Choose where to publish — one chip per environment, only on a project with more than one. See Choosing an environment.
- Website URL — where the site lives, with copy and rename buttons and an Add domain link. See The address.
- Who can view the site — a row under the address. See Who can view the site.
- A security line — the verdict of your latest security scan, such as No security issues found, 2 high-severity issues found or Not scanned for security issues yet. Pressing it opens the Security page. If the scan list can't be read, the line is left out.
- The Publish button. See The Publish button.
The status header
The header says how the environment you're looking at stands, with a line under it:
| Header | Line under it | What it means |
|---|---|---|
| Published | Your website is up to date | The live site was built from what the project holds now. See Up to date, and unpublished changes. |
| You have unpublished changes | The project's files, the environment's variables or the address you're looking at differ from the live build. | |
| Last published 5m ago | Berrybell can't tell whether the live site is current. | |
| Last publish failed · live since 5m ago | The newest publish failed. The build before it is still live. | |
| Publishing… | Building… | A publish is running. The line names the stage — Queued, Building, Uploading or Deploying — or reads In progress when the stage isn't known, such as after a reload. |
| Not published | Publish to put your site online | Nothing has been published to this environment yet. After a failed first publish the line reads Last publish failed. |
While it checks, the line reads Checking your site…. Until you choose an environment on a project with more than one, the header just says Publish.
At the header's right edge, once a production site is live, an eye icon shows its page views over the last 30 days and opens Analytics. Next to it is the more-options menu.
The address
The first row under Website URL is where the site lives, shown as
my-shop.berrybell.app: your project's address in bold and the platform's
domain beside it. Once the environment is published the address is a link that
opens the site; before that it's plain text, the address the first publish will
use. While Berrybell is still working out the address it reads Loading
address….
The buttons on the row:
- Copy link copies the full
https://address. - The pencil renames the address. On the Berrybell address it turns the name
into a field, right there, with the domain beside it. Berrybell checks
availability as you type and turns what you type into a valid address:
lowercase letters, numbers and single hyphens, up to 63 characters. It tells
you when the name is empty (Enter an address.), has no letters or numbers
(Use letters or numbers.), is reserved (That URL is reserved.) or is
taken (That URL is already taken.), and says my-shop.berrybell.app is
available when it's free. Press the tick to save or the cross to cancel.
- The new address goes live the next time you publish. Until then the site is still served at the old address, and the popover reads You have unpublished changes.
- The old address is released as soon as you save, so someone else can register it.
- Your custom domains move to the new address right away. If one can't be moved, the popover says so: app.yourbrand.com will follow the new address when you next publish.
- It renames every environment's address, because each one is built from the project's address (see Where each environment is served). So the pencil is there only while production is the environment you're looking at.
- On a custom domain, the pencil reads Manage this domain and opens Domains instead. To rename the Berrybell address, pick it from the chevron first.
- The chevron appears when the site has more than one address: the Berrybell address plus each custom domain that is ready and not paused. It lists them, with the environment's primary domain tagged primary. The address you pick is the URL the next publish records, and a custom domain you pick becomes that environment's primary. Every address serves the site either way. The pick is remembered in this browser for each project and environment; without one, the popover starts on the primary custom domain, or else the Berrybell address.
Add domain, above the row, opens Cloud → Domains. If Cloud is showing a different environment from the one you're publishing, it opens Workspace settings → Domains instead, which has its own environment picker, so looking at Domains never switches your selected environment. On a free workspace the link carries a Pro badge: custom domains are a paid-plan feature.
Who can view the site
The second row of the address card says who can open the site. A new site reads Visible to anyone with the link. Pressing the row opens Who can view your site?; nothing changes until you press Done. What you set there covers every address the site is published on, and reaches the site within a minute.
On a named environment's own Berrybell address, the row is fixed and reads Only your workspace can view staging — see Where each environment is served.
The Publish button
The button's label says what a press will do:
| The button reads | When |
|---|---|
| Publish | The site has never been published, on a project with only production. Also the label on a project with more than one environment until you choose one — and then the button is disabled, with Choose where to publish as its tooltip. |
| Publish changes | The site is live and you can publish again, on a project with only production. |
| Publish to staging | You chose an environment. The button names it — Publish to production included — on any project where you had to choose. |
| Queued…, Building…, Uploading…, Deploying… | A publish is running. The button is disabled and shows a spinner. |
The button is also disabled in these cases:
- Your website is up to date (its tooltip) — there's nothing new to ship. See below.
- Checking where you can publish… (its tooltip) — the popover is still loading the list of environments. Nothing is published before that answers, so a quick press can't skip the choice a multi-environment project needs.
- While you're renaming the address, until you save or cancel.
Beside the button, the hints from the section above say what the press will do first. On a project with only production, the popover reports how a publish ended above the button: Published to my-shop.berrybell.app with the address as a link, or the reason it failed. On a project with environments, the choice clears when you press Publish, so follow the result on the top-bar button instead.
Up to date, and unpublished changes
After each publish, Berrybell remembers what the live site was built from. Each time you open the popover it compares that with what the project holds now:
- The project's files — changes from the chat, the Code tab, visual edits, restores and undo, and GitHub sync alike.
- The environment's variables — the project-wide values plus that environment's own. See Variables & secrets.
- The icon and preview image you set in Site info.
- The address. One that differs from the live site's is itself something to publish: after a rename the site moves only when you publish, and so does a custom domain you picked in the address list.
The header then says one of three things:
- Your website is up to date. The live site was built from all of the above as they stand. Publish is disabled, because there's nothing to ship. Hover the line to see when it was last published.
- You have unpublished changes. Something differs. Publish is enabled; press it to put the changes live.
- Last published 5m ago. Berrybell can't tell — for example, for a site published before this check existed, or while the AI is still making changes. Publish stays enabled, as it does when the last publish failed.
The check reads your files and variables. Some settings reach your app only when it's published, and it can't see them: turning on sign-in for your app's users, app email or file storage, for example, or data your pages fetch while the site is built. The line can read up to date while one of those is waiting for a publish. When a page tells you to publish — a banner such as Publish this project to turn these emails on — and Publish is disabled, use Publish again in the more-options menu. It rebuilds and redeploys exactly as Publish does, and it's offered only while the site reads as up to date.
The more-options menu
The ⋮ button at the header's right edge opens:
- Site info — the title, description and images search engines and link previews show. See Site info.
- Publish history — the environment's recent publishes. See Publish history. It's disabled until an environment is chosen.
- Domains — the same place as Add domain.
- Publish again — only while the site reads as up to date. See above.
- Open site — the live site in a new tab, once there is one.
Site info
Site info sets how your site appears in search results and link previews: a title (up to 200 characters), a description (up to 500), an icon and a social preview image, with a live Google-style preview of what you're writing. It starts with the project's name as the title.
Save writes these into your app's own code and public files, so the next publish ships them; nothing is deployed by saving. See SEO & discoverability for what to put in them.
Uploading images is the one part that needs the preview running: without it you get "Open the preview to upload images; text metadata was applied." The icon is capped at 100 KB and the social preview image at 500 KB.
The form remembers the title and description per browser, apart from the images: the icon and preview image aren't kept, and saving again without picking them again leaves them out of your app's tags. Open the project in another browser and the form starts over, with the project's name as the title.
Publish history
Publish history shows up to the last five publishes to the environment you're looking at, under the heading Recent publishes to production (or the environment's name). Each row shows the live address as a link, the reason a failed publish failed, or the stage of one that's running, with how long ago it happened. An environment that has never been published reads Nothing published to production yet. Each environment has its own history, so a staging publish never appears in production's list.
Choosing an environment
This applies to a project with more than one ready environment. A project with only production normally sees none of it: no chips, and a plain Publish button. The exception is when the list of environments fails to load (see below).
On a project with more than one environment, the popover starts with Choose where to publish and one chip per environment — production, plus each environment you created that's ready. Nothing is chosen when the popover opens, and there is no default: Publish stays disabled until you press a chip, and the button then names the target, Publish to staging. The rest of the popover follows the chip you pressed:
- the header says whether that environment is published and up to date;
- the address row shows that environment's address, with the chevron for its own custom domains if it has any;
- the page views appear for production only;
- Publish history lists that environment's publishes.
The choice is never preselected. It clears after every publish, including a second publish from the same open popover, so each publish goes where you pointed it that time. That means the popover goes back to its chips while a publish runs. Follow it on the top-bar button, which shows Queued…, Building…, Uploading… and Deploying…, and then a link to the live address, or the reason it failed.
A few more things to know:
- Every environment publishes the same project files. There's no per-environment code; each environment brings its own database, variables, file storage and address — see What an environment is.
- Each environment offers its own domains. Choosing staging lists staging's Berrybell address and any ready custom domain attached to staging, never a production domain. See Domains and environments, which also notes that domains on environments other than production aren't available everywhere yet.
Messages you might see here:
- "staging is no longer available to publish to. Choose where to publish again." — you pressed a chip while the popover was still loading its list, and the list it loaded no longer offers that environment (it was deleted or is resetting, or the list failed to load). Your choice was cleared; pick again.
- "No environment named "staging" for this project." — the environment was deleted after the popover opened. The popover checks the list only when it opens, so close and reopen it.
- "We couldn't load your environments, so only production is listed. Close and reopen this menu to try again." — on any project, production is then the only chip, and you still have to press it to publish there.
- "Environment "staging" is provisioning — wait for it to be ready, then publish." — the publish went to an environment that is still being set up or reset, and was refused.
Where each environment is served
Every environment has its own address, built from the project's address:
| Environment | Address | Who can open it |
|---|---|---|
| production | <project address>.berrybell.app, such as my-shop.berrybell.app | Whoever the site's visibility allows: anyone with the link, until you change it. |
| A named environment | <project address>--<name>.preview.berrybell.ai, such as my-shop--staging.preview.berrybell.ai | Your workspace only, and that can't be changed. The popover reads Only your workspace can view staging. |
- A named environment's address is a private preview address. It sits behind the same signed workspace cookie as the automatic preview, so the link won't open for someone outside your workspace.
- A custom domain is different. One attached to a named environment serves that environment's app to whoever the site's visibility allows, so anyone with the link unless you've changed it. Keep that in mind before you put staging on a domain of its own.
- Nothing is served at an environment's address until you publish to it.
- Renaming changes all of them. The project's address is part of every environment's address.
The "Edit with BerryBell" badge
A published app on a free workspace carries a small Edit with BerryBell badge, and the toggle for it is locked. On a paid plan the badge is off by default and the toggle is yours — you can switch it back on if you want to. The toggle is under Workspace settings → General, labelled Show "Edit with BerryBell" badge; it is not in the Publish popover.
The badge follows the workspace's plan, not the deploy: upgrade and it comes off your already-published apps without republishing, and it returns if the paid plan lapses.
Watching it go out
The top-bar button reports the deployment as it happens — Queued → Building → Uploading → Deploying — and then shows either the clickable live URL or the reason it failed. The popover's button shows the same stages.
A publish can sit at Queued… for a while. Builds on one project run one at a time, first come first served, so a publish waits while:
- the preview machine gets your project's files and dependencies in place — a brand-new machine installs dependencies first; or
- another build for the project is ahead of it, including the automatic preview build that follows a chat run.
Waiting for the files is capped at 10 minutes. After that the publish fails with "dispatch failed: The project's files were not ready on its VM after 600s." If preparing the files fails outright, you get "dispatch failed: The project's files failed to prepare on its VM — reopen the preview and try again." And if Publish has to start the preview while you're already at your limit of running previews, it fails with "Maximum active previews (N) reached" — see Sessions start early, and don't run forever.
The status is polled while the page stays open. Reload mid-deploy and the top-bar button loses the stage, but the deployment carries on: the popover's header still reads Publishing…, and Publish history still lists it.
Publish isn't blocked while a chat run is making changes, and the build uses your project's files as they are when it starts. Publish in the middle of a run and you can ship a half-applied change. Wait for the run to finish.
Publishing from the chat
You can also ask the assistant to deploy for you. Be aware that the chat route defaults to publishing a preview, not production — use the Publish button for the public site.
A chat publish also differs from the button in these ways:
- It needs the preview running. The chat doesn't start one for you. Without it you get "No active preview session for this project — open it first, then publish".
- Its preview is the automatic one. It rebuilds the automatic preview on the selected environment's data.
- It can't publish to an environment you created. Use Publish and choose the environment there.
- It never picks production for you on a project with more than one environment. A chat publish that would go to production stops instead, with "This project has more than one environment, so publishing needs you to choose where it goes. Use Publish and pick an environment."
Automatic preview deploys
Separately from publishing, after any successful chat run that changed something, Berrybell rebuilds and redeploys your project to a preview address, and the preview pane shows that published build, badged Published with a link out to it.
The build runs on the data of the selected environment — production's, unless you've selected another one in the top bar. On a project with more than one environment the badge names that environment instead, such as Preview · staging. If the selected environment was deleted or isn't ready, no build is made, and the pane says why — for example "The preview wasn't deployed because staging no longer exists. Choose an environment."
This matters more than it sounds: it's a real deploy, which is what makes server routes, API endpoints and webhooks actually work in the pane. It isn't the same thing as the live dev lane — the select-element (pointer) button switches the pane over to the live lane, and while you're there a Live chip takes you back to the published preview.
Three things to know about it:
- The preview address isn't public. It sits behind a signed workspace cookie that the Studio issues when you open the project, so the link won't open for someone outside your workspace. Publish for that.
- It isn't an environment. It never appears under Choose where to publish, and it can't have a custom domain.
- It uses hosting budget, like any other deploy — see Plans & credits.
Preview vs. published
Publishing is deliberate: your changes stay private in the preview until you choose to push them live.
- Before publishing — your work is visible only to you and your workspace.
- After publishing — the current version is live at your address, and anyone who has the link can open it until you change who can view the site.
- After more edits — keep iterating freely; nothing new goes live until you publish again. The popover tells you when there's something to publish: You have unpublished changes.
This means you can safely experiment. A half-finished change in the preview never reaches your public app. Data is the exception: the preview works on the selected environment's data, which on a project with only production is your live app's (see What the preview shows).
On a project with environments, each environment you created also has its own published address. It's updated only when you publish to that environment, and it runs on that environment's own database.
Updating a published app
Make your changes in the chat, confirm them in the preview, then open Publish and press Publish changes — on a project with environments, choosing the environment again. The live address stays the same and now serves the new version.
Going further
- Use your own domain. Put your app on
yourbrand.cominstead of a Berrybell URL — a paid-plan feature; see Custom domains. - Try changes on a copy first. On a Business plan, environments give you a staging copy with its own database and address.
- Help people find it. Set up titles, descriptions, and social previews — see SEO & discoverability.
- See who turns up. Traffic analytics start collecting as soon as your app is live.
- Own the code. Sync to GitHub to export and extend your app anywhere — also a paid-plan feature.