Documentation
Taking a repository to a live URL, and what Bunderhost expects from it along the way.
Getting started
Bunderhost hosts JavaScript and TypeScript web applications. The application declares what it needs in code: a database, file storage, sign-in, email, background jobs. Bunderhost reads that declaration from a committed blueprint, creates the resources, applies the migrations and runs the application. Nobody writes a hosting configuration by hand.
What it runs
- Bunderstack applications run as a Bun process in a container, on
managed infrastructure or on a server you connect. Their blueprint is
bunderstack.blueprint.yaml. - Workerstack applications run as a Cloudflare Worker. Their blueprint is
workerstack.blueprint.yaml. - Static sites are served from storage, with no process at all.
Bunderhost builds the container image itself. When an application needs
something the generated image does not have, such as LibreOffice, Chromium,
FFmpeg or extra fonts, it commits its own Dockerfile.bunderhost and
Bunderhost builds that instead: see Application image.
Three ways in
- A GitHub repository. Pushing deploys, pull requests get preview environments. Start from New project.
- A local folder.
bunx bunderhost deployuploads the source and deploys it, with no GitHub account.bunx bunderhost link-repomoves it to GitHub later without losing anything. - An agent. Give a coding agent the prompt on the Projects page, or point it at the page written for agents. It connects through MCP and asks you before anything that needs a yes.
What you can do once it runs
| You want to | Where |
|---|---|
| See what a project is made of and where each part runs | Overview → Project map |
| Ship a commit, follow it, roll back | Deployments tab · bunx bunderhost status, rollback · Deploying |
| Add system packages to the image | Dockerfile.bunderhost · bunx bunderhost dockerfile · Application image |
| Run production on your own server | Organization → Servers · bunx bunderhost target · Your own servers |
| Set variables and secrets | Env tab · bunx bunderhost env · Environment variables |
| Preview a pull request, add a domain | Previews, Domains · bunx bunderhost domains · Previews and domains |
| Read logs, errors, performance | Logs, Errors, Performance tabs · bunx bunderhost logs --runtime · Running in production |
| See how people use it, where they get stuck | Analytics tab · Product analytics |
| Restore or download the database | Data tab · bunx bunderhost db pull · Backups |
| Browse data, files, jobs, users | Data, Storage, Background, Users tabs · Application data |
| Let people sign in with Google or GitHub | Settings · bunx bunderhost auth · Sign-in |
| Send and receive email on your domain | Messaging tab · Email |
| Let an agent do any of the above | Agents and MCP |
Organizations
Everything belongs to an organization. Signing up creates one for you, and projects, servers, GitHub connections, and agent connections all live inside it.
Invite teammates from Organization → Members. Anyone you invite sees the same projects you do. Owners and admins can change a member's role; the owner can transfer ownership.
If you belong to more than one organization, the switcher at the top of the sidebar decides which one you are looking at. A project is only ever visible inside the organization that owns it.
What you need before deploying
- A Bunderstack or Workerstack application, with its blueprint committed at the package root and its database migrations committed beside it.
- For a GitHub project, the repository; for an upload, nothing else.
- Bunderstack 0.23.0 or newer, if you want Bunderhost to verify that your application actually came up after a deploy. Error reporting needs 0.27.0, managed email 0.28.0.
Connect a repository
Install the GitHub App
Open Projects → New project and connect GitHub. You are sent to GitHub to install the Bunderhost App and choose which repositories it may read.
Grant access to the repositories you intend to deploy, and no others. The installation belongs to the organization you were in when you started, and a repository reachable through it can only be used by that organization. An admin of the GitHub account can move the installation to another organization; projects of the previous one keep deploying.
If a repository is later removed from the installation, or the App is uninstalled, the project page says so and owners and admins get an email. Deploys resume once GitHub can reach the repository again.
Choose the repository and its root
Pick the repository, then the package directory — the folder containing the
package.json of the application you are deploying. It is . for a single
application repository, and something like apps/web in a monorepo.
The root directory is where Bunderhost looks for the blueprint. Getting it wrong is the most common reason a first import reports a missing blueprint. The build itself always starts from the repository root, so a monorepo package can use its sibling workspace packages.
Without GitHub
bunx bunderhost deploy in the application folder creates a project from an
upload and deploys it after one browser approval. Upload releases are
manual: there are no pull-request previews, and the folder on your machine is
the only copy of the source. Run bunx bunderhost link-repo once the code is
on GitHub; the project keeps its URL, data, secrets and history and deploys on
every push from then on.
Reusing an existing project
One repository maps to one project. If a project already exists for the
repository in this organization, use it rather than creating a second — two
projects pointing at the same repository will fight over the same branch.
bunx bunderhost link attaches a local directory to an existing project.
The deployment blueprint
bunderstack.blueprint.yaml is the contract between your application and
Bunderhost. Bunderstack generates it from your code; you commit it. Bunderhost
reads the committed file and never imports or executes your application to
find out what it needs. A Workerstack application commits
workerstack.blueprint.yaml the same way.
What it declares
- The framework and the build and start commands.
- Environment variables, each marked required or optional, server or client.
- Database dialect, migrations directory, and migration mode.
- Storage buckets and their visibility.
- Background workers, jobs, cron, and maintenance schedules.
- Email channels and whether they receive mail.
Bunderhost provisions from these declarations. A bucket that is not declared is not created; a variable that is not declared is not asked for.
The blueprint says nothing about the operating system. Packages the
application calls outside JavaScript — LibreOffice, Chromium, FFmpeg,
ImageMagick, fonts — belong in a committed Dockerfile.bunderhost; see
Application image.
Keeping it current
Regenerate and commit the blueprint whenever the shape of your application changes — a new bucket, a new required variable, a changed migration mode.
The project page shows the blueprint status. Ready means the file was read at the current commit. Failed means it was missing, too large, invalid, or GitHub was unreachable; the reason is shown with it.
Migrations
Production databases apply committed Drizzle migrations. Generate them and commit them alongside the code that needs them — Bunderhost will not invent a schema change at deploy time, and refuses an application whose blueprint still pushes its schema.
Bunderhost applies the pending migrations itself, during the deployment:
after the image is built and before the new version receives traffic. A
failed build therefore never leaves a migrated database behind, and a failed
migration stops the deployment while the previous version keeps serving.
Migrations are never reversed, including by a rollback. Each deployment's
Migrate stage lists what it applied, as does bunx bunderhost status.
Environment variables
Where values come from
The blueprint declares the keys. You supply the values, per environment, from the project's Environment page.
Required keys without a value block a deploy. Optional ones do not. If the blueprint declares nothing, there is nothing to fill in — that is a complete answer, not an empty form.
Some variables are the platform's to set, on every deployment: APP_URL and
APP_HOST (the public address), AUTH_SECRET, NODE_ENV, PORT, the
database and storage connection (BUNDERSTACK_DATABASE_URL,
BUNDERSTACK_S3_*) and BUNDERSTACK_REVISION. They never appear on the
Environment page, setting one is refused, and bunx bunderhost env list names
them so nothing has to be guessed. An application that needs its own address
before the first deployment reads APP_URL at runtime rather than at build
time.
Server and client variables
A key the blueprint declares with scope: client is compiled into the
browser bundle: Bunderhost passes it to the build as a Docker build argument,
and it changes only with a new build. Every other key reaches the running
process alone. A custom Dockerfile.bunderhost must declare each client key
with ARG; see Application image.
Configuration and secrets
There is one set of variables. The blueprint decides what each key is: a key
declared with sensitive: false is configuration, and every other key —
including one no blueprint declares — is a secret.
- Configuration is shown and edited in place, like any setting.
- A secret shows only whether it is set. It can be overwritten or removed, and its value is never shown again — not in the dashboard, the CLI, or the API.
A value is shown only while both the stored value was written as configuration and the current blueprint still calls the key configuration. Turning a key into a secret hides its value at once; turning a secret into configuration reveals nothing until the value is written again.
Every value is encrypted before it is stored. Keys that no blueprint declares are marked, so leftovers are easy to spot.
From the command line
bunx bunderhost env list [--json] [--preview]
bunx bunderhost env set KEY=value [KEY2=value2 …] [--json] [--preview]
bunx bunderhost env import [--json] [--preview] < .env
bunx bunderhost env unset KEY [KEY2 …] [--json] [--preview]
The commands work in a directory bunx bunderhost deploy has linked. They
change production unless --preview is given. env import reads .env lines
— comments, quotes and export included — and skips empty values, naming
them. Output lists key names only, and whether each became a secret or
configuration; env list prints values for configuration alone.
Changes reach the running application with the next deployment, and every change says so with the command to run.
The CLI acts with a credential for this one project's variables. Approving a
deployment grants it; otherwise the first env command opens an approval page
(--no-open prints the link). It lasts 90 days and is listed, and revocable,
under Organization settings → Agent access.
Setup requested by an agent
An agent working on your project cannot read or write your values. When it finds required keys missing it opens a setup session and hands you a link.
That link is scoped to one project, expires, and works once. You type the values into the dashboard; the agent learns only that you finished.
Deploying
Choosing where production runs
A project deploys to managed infrastructure, to a server you have connected yourself, or — for a Workerstack application in an enabled organization — to Cloudflare Workers. You choose per project, and the choice is explicit: Bunderhost will not pick for you when several are available.
A self-hosted server must be connected and verified before a project can be pinned to it; see Your own servers.
From a linked directory, bunx bunderhost target shows where production runs
and what it could move to; bunx bunderhost target de4 asks the next
production deployment to move it to the server named de4, and
bunx bunderhost target managed moves it back. Nothing is created or torn
down until that deployment runs. A project on Cloudflare moves the same way;
see Moving a project off Cloudflare for
what happens to its domains.
Source uploaded with bunx bunderhost deploy runs on managed infrastructure
only. To run it on your own server, connect its GitHub repository with
bunx bunderhost link-repo, then choose the server.
Triggering a deploy
By default, pushing to the default branch deploys production. In the project's settings you can switch it to deploy only on a GitHub release, or only when you ask.
Deploy an exact commit rather than "whatever the branch points at now" when it
matters which code goes live. Agents are only allowed the exact-commit path.
bunx bunderhost redeploy ships the commit production runs again, which is
how changed variables reach it.
What a deployment does
Every deployment of a container application runs the same steps, and each one writes to the deployment's log:
- Build. The commit is checked out and the image is built from the
generated Dockerfile, or from a committed
Dockerfile.bunderhost. On your own server the build runs on that server. - Migrate. Pending committed migrations are applied to the database.
- Start. A new container starts beside the one serving now, with the environment's variables.
- Health. Bunderhost asks the new container for
/api/healthon port 3000 until it answers, for about a minute. - Switch. Traffic moves to the new container and the old one stops.
If any step fails, the previous version keeps serving. A check that has to run before migrations belongs in the image build; one that has to pass before traffic moves belongs in the container's start command. Both are described under Checking an image before it goes live.
Watching it happen
Open a deployment to read its log, or run bunx bunderhost logs for the last
deployment from this directory (bunx bunderhost logs <deploymentId> for any
other). bunx bunderhost status reports one commit: its build, the
migrations it applied, its deploy and health, and which Dockerfile built it.
A failed deployment's status carries the reason.
Statuses mean:
- building and deploying — in progress.
- live — this deployment is serving production.
- failed — it stopped; the failing step and its error are in the log.
- superseded — it was live, and a later deployment replaced it.
Live is not the same as healthy
A live deployment means the container started and answered /api/health.
It does not mean your application works.
The project page reports application readiness separately: database reachable, schema provisioned, background queue draining. Check readiness before calling a deploy good. This requires Bunderstack 0.23.0 or newer; older versions report readiness as unsupported.
Rolling back
bunx bunderhost rollback lists production's recent releases;
bunx bunderhost rollback <deploymentId> ships one of them again, and
bunx bunderhost rollback --previous returns to the one before the current
release. Agents use the rollback_deployment tool. A rollback is an ordinary
deployment of an earlier commit: it is rebuilt, waits for health, and keeps
the previous version serving if it fails.
A rollback does not reverse database migrations or data. Code that cannot run against the newer schema should be fixed forward instead. On a project that deploys on push, the next push deploys again. Upload projects cannot roll back: an uploaded archive is used once, so deploy the source you want again.
Application image
A Bunderstack application runs from a container image that Bunderhost
builds on every deployment. By default Bunderhost writes the Dockerfile
itself. When the application needs anything outside JavaScript — LibreOffice
to convert documents, Chromium to render pages, FFmpeg, ImageMagick, fonts,
native libraries — it commits its own Dockerfile.bunderhost, and Bunderhost
builds that instead. Workerstack applications and static sites have no image.
The generated image
Without a committed file, Bunderhost generates a three-stage build from the blueprint's build and start scripts:
depsinstalls production dependencies withbun install --production;buildinstalls everything, runs the build script and drops itsnode_modules;web, onoven/bun:1-slim, takes the built source and the production dependencies, setsNODE_ENV=productionandPORT=3000, and runs the start script.
It also writes Dockerfile.bunderhost.dockerignore, which keeps .git,
node_modules, build output, local databases and .env files out of the
build. The generated image contains nothing else: no system packages beyond
what the Bun base image ships.
Your own Dockerfile.bunderhost
Commit Dockerfile.bunderhost at the repository root — the root of the
repository, even when the project's package directory is apps/web. From the
next deployment on, Bunderhost builds it as it is:
- it never reads, edits or rewrites the file;
- the build context is the repository root, so a monorepo can copy its workspace packages;
- Docker builds the file's final stage; no stage name is required;
- a committed
Dockerfile.bunderhost.dockerignorereplaces the generated one, and can be committed on its own to keep the generated Dockerfile with a different build context.
The file stays an ordinary Dockerfile you can build and run locally:
docker build --platform linux/amd64 -f Dockerfile.bunderhost -t app .
docker run --rm -p 3000:3000 --env-file .env app
The deployment log says which file it used (using committed Dockerfile.bunderhost or using generated Dockerfile.bunderhost), and so do
bunx bunderhost status and the MCP get_deployment tool, as image.source.
Start from the generated one
The quickest way to a working file is the one Bunderhost already builds for the project. In a linked directory:
bunx bunderhost dockerfile # print it
bunx bunderhost dockerfile --write # write Dockerfile.bunderhost and its dockerignore
--write puts both files at the repository root and refuses to replace files
that are already there unless --force is given. Add your packages to the
final stage, build it once locally, and commit both files.
What the image must do
Bunderhost does not repair or extend a custom image. The final stage is responsible for all of this:
- target
linux/amd64; - contain Bun, the built application, its production dependencies and every operating-system package it calls;
- start the application with
CMDorENTRYPOINT, listening on0.0.0.0:3000; - answer
GET /api/healthwithin about a minute of starting — Bunderstack serves it for you; - copy the
migrations/directory: Bunderhost applies migrations before the container starts, and the application checks the same journal when it boots. Do not add a migrate command toCMD; - declare every client-scoped variable with
ARGand pass it to the build command, because Bunderhost hands those to the build as--build-arg; - read everything else from the environment at runtime: the database, storage, sign-in and mail settings arrive as variables on every deployment.
Background jobs and cron run inside the application process, as in the generated image.
Example: converting Word and PowerPoint files
LibreOffice converts .doc, .ppt and the other legacy Office formats. This
file keeps the generated layout and adds LibreOffice and fonts to the final
stage only:
FROM oven/bun:1 AS deps
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production
FROM oven/bun:1 AS build
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
# One line per client-scoped variable the blueprint declares:
# ARG VITE_PUBLIC_EXAMPLE
# ENV VITE_PUBLIC_EXAMPLE=${VITE_PUBLIC_EXAMPLE}
RUN bun run build
RUN rm -rf node_modules
FROM oven/bun:1-slim AS runtime
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
libreoffice-writer libreoffice-impress \
fonts-liberation fonts-dejavu-core \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=build /app /app
COPY --from=deps /app/node_modules ./node_modules
# LibreOffice writes its profile under HOME.
ENV NODE_ENV=production PORT=3000 HOME=/tmp
EXPOSE 3000
CMD ["bun", "run", "start"]
Chromium, FFmpeg and ImageMagick work the same way: install the Debian
package in the final stage, and point the application at its binary through
an ENV line if it needs the path.
Checking an image before it goes live
/api/health only says the process is up; it cannot tell that a converter is
missing. Two places in the image can check more, and each stops the
deployment while the previous version keeps serving:
-
In the build, before anything is migrated. A
RUNstep that converts a small committed sample fails the build, and nothing is deployed or migrated:COPY test/fixtures/sample.doc /tmp/sample.doc RUN soffice --headless --convert-to pdf --outdir /tmp /tmp/sample.doc \ && test -s /tmp/sample.pdf -
At start, after migrations and before traffic moves. A start command that runs a short self-test first never reaches
/api/healthwhen the test fails, so the switch does not happen:CMD ["sh", "-c", "bun run selftest && exec bun run start"]Keep it well under a minute: the health wait counts from the container's start.
Bunderhost validates the package and blueprint before every build, but it cannot prove that an arbitrary image contains what the application calls. Those two checks are how an application proves it.
Your own servers
Production can run on a Linux server you already pay for instead of on managed infrastructure. Bunderhost installs what it needs over one command, builds and runs your containers there, terminates HTTPS, ships logs and metrics back, and cleans up old images. It charges nothing for hosting on your own server.
Connecting a server
Add a server by name under Organization → Servers. Bunderhost shows one command to run on the server as root:
curl -fsSL https://<bunderhost>/api/enroll/<token> | sudo bash
The script needs systemd, curl and free ports 80 and 443. It installs Docker
if it is missing (pass -s -- --no-docker-install to refuse), creates a
bunderhost user that only Bunderhost's key can reach, reports the server's
address and SSH host key, and waits until Bunderhost has verified it. The
server is ready when the page says so; there is nothing to click.
Agents connect servers the same way: create_server returns the command,
get_server reports when enrollment is done.
Moving a project onto it
Choose the server in the project's settings, or run
bunx bunderhost target <server-name> in a linked directory. The next
production deployment builds and starts the project there, and
bunx bunderhost target managed moves it back. A project needs a GitHub
repository to run on a server; an upload project connects one with
bunx bunderhost link-repo first.
Pull-request previews keep running on managed infrastructure unless you send them to the server too; see Previews on the server.
What runs on the server
- Builds. The image is built on the server itself, with its own Docker
build cache, so a committed
Dockerfile.bunderhostis built where it runs. The cache keeps at most a tenth of the disk, between 1 and 10 GB. When the disk is nearly full, a build trims the cache first, and the deployment log says how much space that left. - Containers. Each deployment starts a new container next to the live
one, waits for
/api/healthand only then routes traffic to it. The old container stops after the switch; a container that never becomes healthy is removed and the previous one keeps serving. - HTTPS. A Caddy container serves every project on the server and obtains its certificates.
- Logs and metrics. An agent sends container output and CPU, memory, disk and network figures to Bunderhost. Logs stay searchable for 30 days on the project's Logs tab; container log files are size-capped so a chatty application cannot fill the disk.
- Cleanup. A daily job removes Bunderhost's own images older than a week that no environment uses, keeping each environment's live image and the two before it. It never touches other containers, images or volumes.
The server's page shows its charts, containers, open alerts and cleanup history. Disk usage from 80% is a warning, from 90% critical.
A database on the server
A project that runs on your server can keep its database there too, instead of in the managed provider. The data then sits on your machine, in the country and under the control the machine is in.
Turn it on for the server. Open the server's page under Fleet and
press Turn on databases. Bunderhost installs one database service on the
server (a libsql-server container, the same engine the managed databases
speak) in a minute or two; the card shows when it is ready, or why it failed.
An agent does the same with set_server_databases and reads the result from
get_server.
Choose it for a project. When you create a project and pick that server as
the production target, set Database to the server. Through MCP it is
create_project with databaseProvider: "sqld". The choice can be changed
freely until the first deployment makes the database. After that a change is
a move of the data, made by a production deployment; see
Moving the database to a server or back.
A database on a server is not available for a Workerstack application.
What you get:
- One service, a database per environment. Production and every preview have their own database in it. A token opens one database only, and the read-only token agents and the viewer get cannot write.
- Two addresses. The application on the server reaches its database over
a private Docker network and never leaves the machine. Bunderhost, the Data
tab and
get_database_accessreach it athttps://<database>-db.<your servers' zone>, served by the server's Caddy with its own certificate and open only to a signed token. - Everything else as before. Migrations, the Data and Users tabs, contacts and the read-only access an agent can ask for work the same.
What is different from a managed database:
- Backups instead of a restore window. The service keeps no history, so there is no earlier moment to go back to. Bunderhost copies the production database off the server once a day and keeps each copy for seven days; you restore from one of those. See Database backups.
- The database goes where the project goes. The project can move to another server that has databases turned on, and its database moves with it; see Moving a project to another server. To leave servers for managed infrastructure, move the database to the managed provider first; see Moving the database to a server or back.
- Previews. A preview's database is a copy made on the same server, or an empty one if the project asks for that (see Pull request previews). A preview on managed infrastructure reads that database over HTTPS; one that runs on the server itself (see Previews on the server) reads it inside the server. A copy of a large database takes minutes on a small server: about five for 1 GB on two cores.
- Disk and memory are yours to watch. Plan for three times the size of the databases on disk, and twice the size of the largest one free while it is backed up. The service is limited to a quarter of the server's memory (between 256 MB and 2 GB) and restarts by itself if it runs out.
Turning it off removes the service and its storage, so it is offered only when no database is left on the server and no project is set to use it.
Moving the database to a server or back
A project that already has data can take it from the managed provider onto its server, or from the server to the managed provider. In the project's settings, under Deployment target, set Where the database is kept. The choice is offered to a Bunderstack application; On the server needs production to run on, or be moving to, a server that has databases turned on.
Nothing happens when you save. The next production deployment makes the move, after the image is built and before migrations:
- The database stops taking writes. The application keeps answering, and anything that writes fails. The managed provider is told to refuse writes and Bunderhost checks that it does before reading a row; a database that still takes writes is not copied.
- A new database is made at the new place and the old one is copied into it: by the server itself, which reads the managed database over the network or loads the managed one from its own. Every table is checked to have arrived whole.
- Migrations run on the new database, the application starts on it, and production switches.
The database is read-only from step 1 until production is live on the new one. Between two servers side by side, a copy of 250 000 rows took nine seconds; across the network to the managed provider, and for gigabytes on a small server, allow minutes. If anything fails before production is live, the new database is deleted and the old one takes writes again; the choice stays and the next deployment tries anew. After a move the old database is kept, read-only, for seven days.
To move production to a server and its database with it, choose the server first and then the database; one deployment does both. To leave a server for managed infrastructure, set the database to Managed by Bunderhost first and then the target. Daily backups start for a database that arrives on a server and stop for one that leaves; the backups already made are kept for their seven days.
Moving a database that is on a server whose machine is gone to the managed provider is not available: restore it onto another server from a backup first (see below). The command line has no option for this yet.
Previews on the server
A project that runs on a server can run its pull-request previews there as
well. In the project's settings, under Preview Deployments, set
Previews run to On your server, or pass previewTarget: "server" to
the update_project tool; "managed" is the default and the way back. The
choice is offered to a Bunderstack application whose production is on a
server.
- Built and run on the server. Each preview is built on the server and started there as a container of its own, next to production. It may use up to 512 MB of memory and one CPU; production has no such limit. The number of previews a project admits is the limit on how many run at once, so set it to what the server has room for.
- The same link. The preview's address in the pull request and who may
open it are the project's preview settings, as before. When that address
is a preview link of Bunderhost's own (
<project>-pr-<number>.…), the server answers for the preview only through it, so the preview's own name on the server does not go around the access check. - Its data is beside it. With a database on the server, the preview reads its copy inside the server instead of over HTTPS.
- Logs and console. A preview's logs are on the project's Logs tab with the server's other logs, and its console opens on the server.
- Read when a preview is opened. A preview that is already open stays where it started; close and reopen the pull request to move it. The same holds when production moves to another server or back to managed infrastructure: open previews stay on the server they were opened on, and new ones follow production.
Closing the pull request removes the preview's container, image and address from the server. If the server cannot be reached at that moment the preview is closed anyway, and what stayed on the server is removed when it answers again.
Moving a project to another server
A project moves from one server to another the way it moved onto the first:
choose the other server in the project's settings or with
bunx bunderhost target <server-name>, and the next production deployment
starts it there and switches production. The default hostname is repointed.
Custom domains keep being served by the old server for up to 48 hours while
you point them at the new address.
A project whose database is in the managed provider moves alone: its database stays where it is.
A project that keeps its database on its server takes the database along. The other server must have databases turned on. During the deployment, once the image is built:
- The database is frozen: reads go on, and every write is refused with a message that says the database is being moved.
- It is copied into the project's backup bucket, a new database is made on the new server from that copy, and the rows of every table are checked against the copy.
- Migrations run on the new database, the application starts on the new server, and production switches.
The application is read-only from step 1 until it is live on the new server: about as long as a backup and a restore of the database take, a few minutes for a small one and about twenty-five for 600 MB on a small server. If anything fails before production switches, the move is put back: the new database is deleted and the old one takes writes again, and the next deployment tries the move anew. After a successful move the old database stays on the old server, still frozen, for seven days, and the copy the move carried is listed among the project's backups. A visitor who still reaches the old server through a custom domain in those 48 hours gets the application read-only.
Previews opened before the move keep their databases on the old server until they are closed; new previews copy production on the new one.
If the old server is gone, tick the box under the pending move that says so: load the newest backup instead of copying the database. The next deployment then makes the database on the new server from the newest backup and does not try to reach the old server at all. Whatever was written after that backup was made is not in the moved database, so this is for a server that is lost, not for one that is merely slow.
Moving a project off Cloudflare
A project on Cloudflare Workers moves onto a server the same way: choose the
server in the project's settings, or run bunx bunderhost target <server-name>.
The next production deployment starts it on the server and switches
production; the database stays where it is. The revision decides what runs:
a Workerstack app runs under celld, and a Bunderstack app committed in the
same change runs as a container. A static site stays on Cloudflare.
- Custom domains move with production. A domain in the platform's
Cloudflare account is a Workers Custom Domain, whose DNS record Cloudflare
owns. Once the server serves, Bunderhost detaches the domain from the
Worker and writes a DNS-only record for the server in its place: an
Arecord for an apex, aCNAMEto the default hostname for a subdomain. The domain then verifies on the server like any other. Expect a few minutes without it while the record spreads and the server issues its certificate. - A record Bunderhost cannot write is yours to add. The deployment log names it. A record someone already put at that name is left alone and reported, not replaced.
- Domains served through Cloudflare for SaaS cannot move yet. Remove them under Domains, move production, then add them again.
- The Worker keeps answering at its own hostname until the custom domains are live on the server, or for 48 hours, and is then deleted.
- A Workerstack app's files are read from another place in the bucket on a
server: celld keeps them under
celld/r2/<app>-<bucket>/. Until they are copied there, existing files answer 404. Workerstack's hosting guide has the command. A Bunderstack app reads its files where they are. - The client address arrives in
x-forwarded-foron a server. An app that trustscf-connecting-ipshould stop: nothing strips a forged one there. - Going back to Cloudflare, delete the record Bunderhost wrote first: Cloudflare does not attach a domain that already has one.
Changing or removing a server
If the server gets a new address, use Edit address and verify again: Bunderhost checks that it is the same machine by its host key, updates the default hostnames of its projects, the addresses of its previews and of the databases it holds, and lists the custom domains you need to point at the new address.
Removing a server needs a confirmation and takes back what Bunderhost
installed: the agent, Caddy, the database service with its storage, the
bunderhost network and its files. Docker and swap are left alone. Move its
projects elsewhere first. A server cannot be removed while a preview runs on
it or an environment still uses a database on it, which is the case for a
preview opened before its project moved, until that preview is closed.
Databases that are only kept there, after a restore or a move, go with the
server.
Previews and domains
Pull request previews
Opening a pull request against the default branch creates a preview environment and comments its URL on the pull request. Closing the pull request tears the environment down.
Each project admits a limited number of concurrent previews; set the limit, or disable previews, in the project's settings. Previews beyond the limit are skipped and say so rather than queueing indefinitely.
Previews are visible to your organization by default. You can make a project's previews public if you need to share one outside the team.
A preview starts with its own copy of production: a branch of the production
database and a copy of its files. Nothing a preview changes reaches
production. When production data must not leave production, set A new
preview starts with to An empty database and no files in the project's
settings, or previewData: "empty" through the update_project tool. Such a
preview has the tables your migrations create and nothing in them, and an
empty bucket. The setting is read when a preview is created, so a preview that
is already open keeps what it started with; close and reopen the pull request
to start it again.
An empty preview is of little use to whoever opens it, so a Bunderstack
application can fill it itself. The third choice, The application's seed
data (previewData: "seed"), gives the preview an empty database and
bucket and starts it with BUNDERSTACK_SEED=1; the application then runs
its seed, once, before it serves anything: a demo user, sample records,
whatever its code puts there. The choice is offered when the application
declares a seed (database: { seed: () => import('./seed') }, Bunderstack
0.33.1 or later) and the blueprint on the default branch says so. A pull
request whose own blueprint has no seed starts empty, and its deployment log
says so. A seed that fails stops the preview's deployment with the seed's
error in the application's log.
Production is never seeded. Bunderhost passes the variable to previews
opened for it and to nothing else, and BUNDERSTACK_SEED cannot be set as a
variable of your own in any environment.
When the project keeps its database on your own server, the preview's database is made on that server as well, as a copy or empty by the same setting.
A preview runs on managed infrastructure unless the project sends its previews to its own server; see Previews on the server.
A nightly sweep tears down previews whose pull requests closed while a webhook was missed, so a missed event costs you a day, not a leaked environment.
Custom domains
Add a domain to an environment from the project's Domains page. Bunderhost shows the DNS record to create and verifies it before routing traffic.
Until a domain verifies, the environment keeps serving on the address Bunderhost assigned it. Verification is not instant — DNS propagation is outside anyone's control here.
Production can have up to five domains, for example example.com and
sub.example.com. Each gets its own certificate and all of them reach the same
application, which sees the requested name in Host and X-Forwarded-Host.
The first domain is the primary: it becomes the app's URL (APP_URL). Use
Make primary (or bunx bunderhost domains add <hostname> --primary) to
move that role, then deploy. Removing one domain leaves the others serving; a
hostname can belong to only one project. Preview environments keep their
assigned addresses.
For Cloudflare deployments, domains in the platform account use Workers Custom Domains. Domains in another account use Cloudflare for SaaS when the operator has configured it. Create the displayed CNAME and TXT ownership/TLS records in your existing DNS zone. For an apex in Cloudflare DNS, use CNAME flattening. Validate TXT before switching traffic and retain TLS validation TXT records.
Both hostname and TLS validation must be active before the external hostname
routes to your Worker. Pending validation does not block deployment to your
platform URL. Deploy again after activation to update the app's advertised
URL and authentication origins. Inspect status with bunx bunderhost domains check [hostname]; repeating domains add for the same hostname checks the
existing claim.
Running in production
Once a deployment is live, the project's tabs show what the application is doing, and the same information is available to the CLI and to agents.
Logs
The Logs tab is a log explorer: search, time range, a timeline by level, level and instance filters, a live mode and export. On your own servers and on Cloudflare Workers, logs are stored and stay searchable for 30 days across deployments; on managed infrastructure the tab reads what the machine still holds.
From a linked directory:
bunx bunderhost logs --runtime # production, newest 100 lines
bunx bunderhost logs --runtime --since 1h --level error
bunx bunderhost logs --runtime --env pr-12 --query "soffice"
bunx bunderhost logs without --runtime prints a deployment's build and
deploy output instead. Agents use get_runtime_logs and
get_deployment_logs.
Errors and performance
Deployed applications report errors and performance to Bunderhost by themselves; there is nothing to install. The Errors tab groups unhandled exceptions from API procedures, failed jobs and cron runs, process crashes, server-rendering failures and browser errors into issues, with stack traces resolved through source maps. Performance shows request and job durations and Web Vitals.
Server-side reporting needs Bunderstack 0.27.0 or newer; browser reporting
works on any version. Agents read the same data with list_issues,
get_issue and get_performance.
Alerts and daily summaries
A new issue, a regression of a resolved one, or a spike in errors notifies the organization's owners and admins by email, and in Telegram once a chat is paired under organization settings. A project can switch to one daily summary instead of an email per issue, and the organization can fold all such projects into a single summary. The organization's Monitoring section shows every project's open issues in one place.
Readiness
/api/health says the process is up. Readiness says the application works:
its database is reachable, its schema is provisioned and its background queue
is draining. The project page shows it after every deployment, and
bunx bunderhost status and the MCP get_environment_health tool report
healthy only when it says ok.
Database backups
How a database is protected depends on where it is.
A managed database can be restored to any moment within the restore window of the database provider's plan — 24 hours at least. Restoring production from the Data tab creates a new database from that moment, switches production to it and redeploys; the replaced database is kept for seven days.
A database on your own server keeps no history, so Bunderhost backs it up:
- Once a day, production is copied off the server into a bucket Bunderhost keeps for the project. The server is handed a link for that one file and never the bucket's keys, and the application never sees the bucket at all. The first backup is made within minutes of the first deployment.
- Each copy is kept seven days. The newest one is kept however old it is, so a database whose backups stopped is never left with none.
- A backup is a gzipped SQLite file of the database as it was at one moment. Writes carry on while it is made. It is checked before it is stored, and the rows of every table are counted and recorded.
- Back up now on the Data tab makes one on request, for production or a preview. Download hands you the file straight from the bucket.
- Restore… on a backup of production makes a new database on the server from it, checks every table has the rows the backup recorded, switches production to it and redeploys. What production held is backed up first, and the replaced database stays on the server for seven days. Everything written after that backup was made is not in the restored database.
- Daily backups can be switched off on the same card, or with
update_project(databaseBackups: false). Nothing then leaves the server unless you press Back up now.
A day without a fresh backup opens an alert on the server's page under
Fleet, named after the project, and get_server reports it; it closes
with the next backup. A backup fails when the server cannot be reached, or
when it lacks free disk for the copy: about twice the size of the database.
On a small server (two cores, 1 GB of memory, a network disk) a backup of a
600 MB database takes about eleven minutes and a restore about thirteen; the
application keeps reading and writing throughout, with an occasional write
slowed to a second or two by the shared disk.
Any environment's database can be downloaded as a SQLite file from the Data tab or with:
bunx bunderhost db pull # production, now
bunx bunderhost db pull --at 2026-11-10T08:00:00Z --output before.db
bunx bunderhost db pull --preview 12
For a managed database that is the database now or at a moment in its
window. For a database on a server it is a backup made on request, and --at
is refused: an earlier state is one of the backups on the Data tab.
Console
Organization owners and admins can open Console on a live deployment: a shell inside the running container, on managed infrastructure or on your own server. It never starts a replacement container. Production asks for an extra confirmation, sessions close after 30 minutes, and only who opened a session and when is recorded — never what was typed or printed.
Analytics and usage
The Analytics tab counts visitors, pages, events and referrers of the production site and records a sample of visits, without any script of your own; Product analytics covers what is collected and what an agent can read. Organization → Billing shows this month's compute, database and storage usage per project, with a forecast to the end of the month.
The tracker is added to a Vite application's build: a script from
Bunderhost's own address (the one the dashboard is on) loads the analytics
script from the analytics host, which receives the visits. Browser errors
for the Errors tab are sent to Bunderhost's address too. An application
that sends its own Content-Security-Policy header has to allow both
addresses in script-src and connect-src. Otherwise the browser blocks
them: Analytics stays empty and Errors shows only the server's
errors. The analytics host is the address in the
script at <dashboard>/app-analytics/<id>.js that your page loads. Visits
count only on the project's own addresses: its default hostname and its
custom domains, not a proxy of your own in front of them.
Product analytics
Every production site counts its visits and records a sample of them without
any script of your own, and an agent can read both: which step of a sign-up
people abandon, what the visitors who reached /error saw, whether a fix
changed anything. The Analytics tab shows the overview and opens the full
reports.
What is collected
The tracker is added to a Vite application's build (see
Analytics and usage for the addresses a
Content-Security-Policy has to allow). It runs in production only; previews
collect nothing.
- Visits, pageviews, entry and exit pages, query strings, referrers, campaign
(
utm_*) parameters, device, browser, operating system, country and region. - Custom events the application sends, and their properties.
- Web Vitals per page.
- Session recordings and click and scroll heatmaps of a sample of visits: 15% each by default, recordings up to five minutes long.
Visitors whose browser sends Do Not Track are not counted, and ad blockers hide some others, so the numbers are a floor. Analytics → Settings turns collection, recordings and heatmaps on or off, sets the sample rates and the longest recording, and chooses masking. Collection stops without a redeployment.
Privacy
Recordings use strict masking by default: every text on the page is replaced
by * and every input is masked, so a recording shows the layout and the
movements, not what a visitor read or typed. Moderate masking shows page text
and still masks inputs. An element marked data-private or
data-bunderhost-private is left out of recordings entirely, with everything
inside it.
Credentials in URLs never leave the browser. Before the tracker sends a visit,
values of query keys such as token, code, state, email, password,
session or signature, emails, JWTs and long random strings are replaced
by [redacted], and a path segment that looks like one becomes :token, so a
password-reset link is counted as /reset-password?token=[redacted]. error
codes and utm_* values are kept. Recordings store the address as the browser
had it; it is redacted whenever an agent reads one.
Page titles are sent as they are, and an agent reading a recording sees
element attributes such as aria-label, title, alt and placeholder. Do
not put a person's name or details in them.
Custom events and identity
Pages, referrers and recordings need nothing from the application. To measure a step that is not a page, such as a completed sign-up, send an event from the browser:
window.umami?.track('signup_completed', { plan: 'pro' })
The event name becomes a funnel or goal step, and its properties can be
broken down. To link the visits of one signed-in person across devices, call
window.umami?.identify('usr_4821') with your own user ID, never an email
address: whatever is passed is shown to anyone who can read individual
sessions.
What an agent can read
| Permission | Tools | Granted |
|---|---|---|
analytics:read |
get_analytics, get_analytics_funnel, list_analytics_definitions |
with read access |
visitors:read |
list_visitor_sessions, get_visitor_session, get_recording |
by an owner or admin, when the agent asks |
analytics:write |
save_analytics_definition, delete_analytics_definition, save_recording, set_analytics_collection |
with full access, to owners and admins |
get_analytics answers about twenty named reports: an overview against the
previous period, a time series, pages, query strings, referrers, channels,
campaigns, locations, technology, custom events and their properties, Web
Vitals, journeys, retention, goals, attribution, revenue, scroll depth, a
breakdown by up to three fields, and the last 30 minutes. These are aggregates
only: a breakdown by one visitor is not one of them.
With visitors:read, an agent lists the sessions behind a drop-off, such as
those that reached /signup and never sent signup_completed, and reads
their recordings. A recording is never returned as video or as the page: it is
a timeline of pages, clicks, inputs (which field, never the value), scrolls and
pauses, with elements named by tag, a short CSS path and attributes such as
id or data-testid. Signals mark where a visitor seemed stuck: repeated
clicks on one spot, a click that changed nothing, a control that answered
after two seconds, a switch flipped back and forth, a form left without
submitting, an immediate return to the previous page, and error pages.
With analytics:write, an agent saves funnels, goals, segments and notes on
the charts, bookmarks recordings for a person to watch, and changes sampling.
A change can carry an end date at most 14 days ahead, after which the previous
settings come back by themselves, so "record every visit for a week after the
launch" cannot be forgotten. Masking cannot be loosened by an agent, and a
change in Analytics → Settings replaces any temporary one.
Bunderhost marks the charts by itself too: every production deployment
(Bunderhost: Deployed 4f2a9c1 Fix the consent switch) and every approved
broadcast. Notes an agent writes begin with Agent:.
Connected agents read the workflow as the resource
bunderhost://guide/product-analytics.
Application data
The tabs in a project's Data and Users groups read and change what the application itself stores, per environment. They are for looking and for the occasional fix; build product features in the application.
Data and storage
Data lists the database's tables and their rows, and holds the environment's backups. Storage lists the files in the environment's buckets. Both follow the environment selected at the top of the project.
Background jobs
Background lists queued, running, finished and failed jobs and cron runs with their errors, so a failed job can be read without opening the logs. Job history is kept outside the application's database.
Users
Users lists the people registered in the application — not your organization's members — with their sessions. From there you can change a user's role, ban them where the application supports it, end their sessions or delete them.
Contacts and broadcasts
Applications on Bunderstack 0.31 and newer keep Contacts: people they write to who need not be users. The tab searches, tags, imports and exports a CSV, and unsubscribes. From Bunderstack 0.32, Broadcasts drafts one email to many contacts with a live preview and recipient count, sends a test, and sends now or at a set time; an agent can prepare a broadcast, but only an owner or admin sends it.
A contact joins a list in one step, from wherever the application learns about
a person: its own code (ctx.contacts.upsert with a tag such as
newsletter), a form on its pages posting to Bunderstack's capture endpoint,
a CSV import or the editor on this tab, or an agent with upsert_contacts.
There is no confirmation email; an application that wants a double opt-in
builds it with a holding tag (the Bunderstack contacts docs show how). Every
broadcast carries a one-click unsubscribe link, and an address that
unsubscribed, bounced or complained is never written to again.
What an agent may read
Customer data is never part of an ordinary agent connection. Reading tables,
files, jobs, users, contacts or individual visitor sessions needs its own
permission (data:read, storage:read, jobs:read, users:read,
contacts:read, visitors:read), which an owner or admin grants in the
browser when the agent asks. Analytics aggregates are not customer data and come with read access
(Product analytics). What it reads is treated as
untrusted data, never as instructions.
With data:read, list_app_tables shows each table's columns, primary key
and indexes, and read_app_table reads only the rows an agent asks for, so
finding one record is one call however large the table is:
{
"table": "orders",
"where": [
{ "column": "customer_id", "op": "eq", "value": "cus_0042" },
{ "column": "created_at", "op": "gte", "value": "2026-11-01" }
],
"columns": ["id", "status", "total"],
"orderBy": { "column": "created_at", "direction": "desc" },
"count": true
}
Filters combine with AND. The operators are eq, ne (rows without a value
count as not equal), in (up to 100 values), gt, gte, lt, lte,
contains and startsWith (case-insensitive for ASCII; % and _ are
plain text), isNull and notNull. A range filter given an ISO 8601 date
compares points in time, whether the column keeps seconds, milliseconds or
text. Without orderBy rows come in primary-key order. The answer's
page.nextCursor continues the same read and costs the same on any page;
offset still works but reads every row before it. count: true adds
total, the number of rows the filters match.
Columns named like credentials (password, secret, token, credential, API or private key) are left out of every row, and a filter, sort or column list that names one is refused.
Sign-in and email
Sign in with Google and GitHub
An application can offer Google and GitHub sign-in without registering an OAuth application of its own. Turn the providers on in the project's settings, or from a linked directory:
bunx bunderhost auth providers
bunx bunderhost auth enable google
bunx bunderhost auth disable github --env pr-17
The provider keys stay with Bunderhost's identity service; the application
keeps its own users and sessions. The application receives sign-in with a
deployment, so the first time a provider is turned on, production deploys the
commit it runs again by itself and sign-in works once that deployment is live.
A preview, or an application deployed from uploads, gets it with its next
deployment; the settings card and get_project_readiness say when one is
still needed. After that, turning providers on and off applies without a
deployment. Turning a provider
off stops new sign-ins and leaves existing sessions until they expire. It needs
Bunderstack 0.26.0 or Workerstack 0.1.5 and newer.
An application that declares an email() channel sends mail without an
account of its own. On the Messaging tab:
- Connect a domain. Bunderhost shows the DNS records to create; once they
verify, production sends from that domain. A channel declared with
ses({ receive: true })also receives mail sent to the domain, delivered to the application with retries for three days. Receive on a subdomain such asmail.example.com, because its MX record takes over all mail for that name. - Choose the provider. Hosted delivery, or your own Resend account. Switching redeploys production and open previews.
- Set the sender of each channel, so a newsletter can send from its own subdomain.
Managed email needs Bunderstack 0.28.0; the provider switch needs
Bunderstack 0.30.0 or Workerstack 0.5.0. A channel declared with ses() or
resend() keeps that provider whatever the switch says, so move it to
email() to choose on the tab. Agents manage domains with
connect_mail_domain and check_mail_domain, and the provider with
set_mail_provider.
Agents and MCP
Bunderhost exposes an MCP server so a coding agent can read project status, logs, and deployments, and — with your approval — create projects and deploy them.
The shortest way to start is to give your agent the prompt on the Projects page. It sends the agent to the page written for agents, which covers supported stacks, connecting, and the path from a source tree to a live URL.
Connecting an agent
Add an MCP server named bunderhost at /mcp on this host, using the HTTP
transport. The first request answers with OAuth metadata, and a compliant
client opens a browser: you sign in, choose which organizations the agent may
work in, and choose Read only or Full access. Nothing is pasted
anywhere. Manage and revoke these connections under Account → MCP
connections.
Clients without a browser
CI, servers and MCP clients that cannot do OAuth use a token instead. An owner or admin creates one under Organization → Agent access, names it after the agent or device, picks its permissions and lifetime, and copies it once into that client's configuration. A token that only reads cannot change anything, and revoking one takes effect immediately. An agent never needs to ask a person for a token in chat.
What an agent reads first
After connecting, an agent reads the guides the server publishes as
resources: bunderhost://guide/project-onboarding takes a repository to a live
URL, bunderhost://guide/product-analytics finds where people get stuck in a
production app, from funnels to recordings, bunderhost://guide/personal-apps builds an app without a repository
from a starter that uses every platform feature (sign-in, data, both kinds of
storage, jobs and cron, outgoing and incoming mail, a webhook, contacts, and
a seed with a demo user for previews and local development), and bunderhost://organization/context says which targets, GitHub
connections and balance the organization has. Every page of this
documentation is also a resource, bunderhost://docs/<section> — for
example bunderhost://docs/application-image — so an agent can read the
same contract a person reads here.
What always needs you
Creating a project and deploying a revision require either your per-call confirmation or a browser-approved deployment policy for that connection. Declining changes nothing.
If your MCP client cannot show a confirmation and no matching delegation exists, the agent requests browser approval. Deletion and other confirmation-only actions require a compatible client or the dashboard.
An approval link stays open for 24 hours. Every open request also waits at the top of the dashboard for the organization's owners and admins, with a Review link, so you can approve after the chat that asked has moved on.
A deployment policy can also carry auth:write. Then one approval covers
creating a project, deploying it and turning on its Google or GitHub sign-in:
the policy names the repository or app, and sign-in is limited to that
project's production. Previews and application users still need their own
approval.
What an agent never sees
Environment values, provider credentials, encrypted keys, and session data are not returned by any tool. When an agent needs a secret set, it opens a setup session and you type the value into the dashboard.
Operators
Platform-wide access across organizations is a separate endpoint with separate credentials, meant for Bunderhost operators. It is not part of connecting an agent to your project, and the two credentials should never share a workspace.
OAuth connections
The consent page shows the client, selected organizations and either Read only or Full access. You can select several organizations or all currently listed organizations. The selection is a snapshot: future organizations need another consent. Full access remains limited by your current role in each organization; leaving an organization removes access and a downgrade removes writes.
Manage your own connections and revoke access from Account → MCP connections. Organization managers can also revoke individual grants under Agent access. A new consent replaces the organization selection for that client/user pair, including its existing access tokens.
Agents use get_connection_capabilities to inspect effective permissions. Each
tool accepts organizationId; resource clients can use the
X-Bunderhost-Organization header. get_environment_diagnostics gathers available
health, deployment, readiness, migration and log diagnostics. Missing permissions
are reported explicitly. Build, deployment and approval waits accept
waitSeconds up to 50, which keeps each call inside the 60-second request
timeout of most MCP clients; larger values wait 50, and the agent calls again
while timedOut is true. Persistent build, deployment and plan IDs let the
agent resume after a disconnect.
rollback_deployment uses the same approval and deployment-policy checks as a
normal deployment. It deploys a previously successful immutable revision; it does
not reverse database migrations, and temporary upload source may no longer exist.
Application table, file and background-job reading requires separate explicit
data permissions. Ordinary read/full OAuth presets do not include customer data.
Reading sign-in settings (auth:read: which providers are on and whether they
work, no users and no secrets) is part of read access, including for
connections made before it was. Changing sign-in and reading application users
keep their explicit approval for one environment. Scope expansion and a deployment policy are browser approvals;
an event subscription cannot supply either one.
Event monitoring
With a compatible client, an agent can subscribe to deployment failures,
environment health degradation/recovery, ready previews, failed background
jobs, and application errors that open, regress or spike. The server implements authenticated MCP 2.0 event discovery and
events/list, events/subscribe, events/unsubscribe on /mcp.
Subscriptions and pending deliveries persist across server restarts. Webhooks require public HTTPS, a verified callback and signatures. Deliveries use stable event IDs and bounded retries, and stop when the underlying access is revoked. They carry resource IDs and status, never secret configuration or job payloads.
Deployment and preview events are queued when their state changes. Health and background job failures are sampled once a minute; transient changes between samples can be missed. Job sampling examines at most 1,000 recent jobs per environment. Subscriptions have a finite lifetime of at most seven days and must be refreshed. No replay cursor is offered; pending deliveries survive a restart, but an expired subscription cannot recover its gap through the protocol.
ChatGPT currently supports events in Work web, Work desktop with Cloud selected, and dots. Tool-only MCP clients continue to use read/wait calls. See the ChatGPT MCP Events documentation for client support. Receiving an event grants no additional authority to act.
For rollback retries, reuse idempotencyKey; use a new key for a later intentional
rollback to the same historical release. A branch-head policy cannot approve an
older commit: that requires explicit confirmation in a compatible client. Uploaded
archives are single-use; the tool returns a recovery action to stage a retained
prepared revision or upload the original source again.
Command line
bunx bunderhost works in an application folder and needs no install. The
first command in a folder links it to a project; later commands act on that
project. Each command that changes something asks for approval in the
browser once, and --no-open prints the link instead of opening it. Every
command takes --json and then writes one JSON event per line, which is
what agents read.
| Command | What it does |
|---|---|
deploy |
Upload this folder and deploy it; creates the project the first time. |
link [--project <id>] |
Attach this folder to an existing project. |
link-repo [--branch <name>] |
Deploy on every push from the GitHub repository in origin. |
status [--sha <rev>] [--env <name>] [--wait] |
One commit's build, migrations, deploy, health and image. |
logs [<deploymentId>] |
A deployment's build and deploy output. |
logs --runtime [--env] [--since] [--level] [--query] |
What the running application printed. |
redeploy |
Ship the commit production runs again, to apply new variables. |
rollback [<deploymentId> | --previous] |
List earlier releases, or ship one of them again. |
target [managed | cloudflare | <server>] |
Where production runs, or move it. |
dockerfile [--write [--force]] |
Print or write the Dockerfile Bunderhost generates for this project. |
env list | set | import | unset |
Read and change variables; secrets are never printed. |
domains [list | add | check | remove] |
Custom domains, up to five per environment. |
db pull [--at <time>] [--preview <N>] |
Download a database as a SQLite file. |
auth providers | status | enable | disable |
Google and GitHub sign-in. |
Exit codes: 0 done, 1 failed, 2 wrong arguments, 3 not finished yet
(status and auth while something is still settling).
bunx bunderhost --help lists every flag.