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 deploy uploads the source and deploys it, with no GitHub account. bunx bunderhost link-repo moves 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:

  1. 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.
  2. Migrate. Pending committed migrations are applied to the database.
  3. Start. A new container starts beside the one serving now, with the environment's variables.
  4. Health. Bunderhost asks the new container for /api/health on port 3000 until it answers, for about a minute.
  5. 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:

  • deps installs production dependencies with bun install --production;
  • build installs everything, runs the build script and drops its node_modules;
  • web, on oven/bun:1-slim, takes the built source and the production dependencies, sets NODE_ENV=production and PORT=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.dockerignore replaces 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 CMD or ENTRYPOINT, listening on 0.0.0.0:3000;
  • answer GET /api/health within 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 to CMD;
  • declare every client-scoped variable with ARG and 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 RUN step 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/health when 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.bunderhost is 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/health and 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_access reach it at https://<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:

  1. 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.
  2. 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.
  3. 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:

  1. The database is frozen: reads go on, and every write is refused with a message that says the database is being moved.
  2. 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.
  3. 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 A record for an apex, a CNAME to 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-for on a server. An app that trusts cf-connecting-ip should 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.

Email

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 as mail.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.