# Bunderhost for agents

You are reading this because a person asked you to build or deploy a web
application on Bunderhost. This page is the whole path: what Bunderhost runs,
how to start an application it can host, how to connect to the person's
account, and how to take the source tree to a live URL. It is public and needs
no sign-in. The same text is served as plain Markdown at `/llms-full.txt`.

## What Bunderhost runs

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
file, creates the resources, runs the migrations and serves the application.
Nobody fills in a hosting configuration by hand.

Two kinds of application are supported today:

- **Bunderstack** runs as a Bun process. Its blueprint is
  `bunderstack.blueprint.yaml`. This is the default choice.
- **Workerstack** runs as a Cloudflare Worker. Its blueprint is
  `workerstack.blueprint.yaml`.

An application on any other stack has to be moved to one of these two before
Bunderhost can host it. Say so plainly instead of trying to deploy it as it is.

System packages are not a reason to leave. A Bunderstack application that
needs LibreOffice, Chromium, FFmpeg, fonts or native libraries commits its own
`Dockerfile.bunderhost` at the repository root, and Bunderhost builds it
instead of the generated image; `bunx bunderhost dockerfile --write` writes
the generated one as a starting point. The contract is in the Application
image section of the documentation, which follows the guides below.

## Start from an empty directory

Install the framework's agent skills first. This works before anything else is
installed and gives you instructions that match the released version:

```sh
bunx bunderstack skills
```

Then follow the `creating-bunderstack-apps` skill it installs. For a Cloudflare
Worker, run `bunx workerstack skills` and follow `create-workerstack-app`.

Framework reference, cheapest first:

- Bunderstack index: https://bunderstack.kcrz.dev/llms.txt
- Bunderstack in full: https://bunderstack.kcrz.dev/llms-full.txt
- Workerstack: https://github.com/kirill-dev-pro/workerstack

## Start from an existing repository

Look for a committed `bunderstack.blueprint.yaml` or
`workerstack.blueprint.yaml` at the package root. If one is there, the
application is ready to connect. If the application uses the framework but has
no blueprint, generate it with `bunx bunderstack blueprint` (or
`bunx workerstack blueprint`) and commit it together with the database
migrations.

## Develop locally

Local development needs no setup. `bun run dev` starts the application with
its database, file storage, sign-in and background jobs created at runtime on
the person's machine. There is nothing to provision and no account to connect
until the first deploy.

## Connect to the person's account

Bunderhost is operated through an MCP server at `/mcp` on the same host as
this page. The prompt the person gave you normally carries the exact address.

1. Add an MCP server named `bunderhost` at that address, using the HTTP
   transport.
2. The first request is answered with 401 and OAuth metadata. Follow it and
   give the person the authorization link.
3. The person signs in or creates an account in the browser, chooses which
   organizations you may work in, and chooses read-only or full access.
4. Call `get_connection_capabilities` to see what the connection allows.

Never ask for a token, a password or an API key, and never paste one into a
configuration file. The browser flow is the only way in.

Without a terminal or a repository, for example in a chat client, read the
`bunderhost://guide/personal-apps` resource after connecting: the application
source is then written and built through the MCP tools themselves.

## What always needs the person

- Creating a project and deploying to production need an explicit yes: a
  confirmation in your client, or a deployment policy the person approves in
  the browser.
- Secret values never go through the chat. Open a setup session with
  `create_setup_session` and give the person the URL.
- Creating or pushing a GitHub repository needs their consent.
- Deleting anything needs their confirmation.

Report an application as live only after its deployment reached a terminal
state and `get_environment_health` says `ok`. A URL alone proves nothing.

# Source tree to live URL

1. Ask whether the person has a GitHub account. Quietly checking git or gh does not replace their answer and never authorizes creating or pushing a repository.
2. Prefer a private GitHub repository: it preserves history, makes recovery easier, and enables automatic deploys and pull-request previews. Ask before creating or pushing it.
3. If they have no account, decline, or one useful setup attempt fails, offer two real choices: retry GitHub, or deploy a ZIP now. State the upload trade-offs once: releases are manual, there are no PR previews, and the local folder is the only source copy after deployment deletes the archive.
4. For GitHub, resolve_repository and reuse an existing project. Connect the GitHub App, call list_deployment_targets, create_project with source github and an explicit target (the cloudflare target takes only Workerstack apps, those with a committed workerstack.blueprint.yaml, and supports external custom domains when Cloudflare for SaaS is configured; use the project domain dashboard for DNS validation), configure missing values, and deploy_revision with an exact 40-character commit SHA.
5. For upload, generate committed migrations and bunderstack.blueprint.yaml, run blueprint:check and the verification contract, then create_project with source upload on managed infrastructure.
6. Call create_source_upload. PUT a ZIP of the project root directly from the local shell to uploadUrl with Authorization: Upload <credential>. Never send archive bytes through model context. Exclude node_modules, .git, .env, and .env.* and do not add a wrapper directory.
7. Call get_source_upload. Continue only from ready, then call deploy_revision with the upload id and confirm.
8. If required configuration is missing, use create_setup_session, or set_environment_variables for values you already have. Never ask for secret values in chat.
9. Wait on get_deployment with waitSeconds until it leaves building and deploying, then call get_environment_health and report success only when readiness is `ok`.
10. After an upload succeeds, offer once to push the current tree to GitHub and call attach_project_repository. It is a permanent source change but preserves URL, data, secrets, resources, and deployment history.

deploy_project is legacy: it deploys whatever the default branch points at, without confirmation. Use deploy_revision.

If the client cannot present a confirmation, create_project and deploy_revision refuse and change nothing. Say so and point the user at the dashboard rather than looking for another way in.

# Bunderhost agent guide

Bunderhost imports and operates Bunderstack repositories for one authenticated organization. Use this MCP server for hosted projects, deployments, logs, configuration status, and readiness. Do not read a local Bunderhost data.db or call the legacy operator automation API for an organization workflow.

New users can use the configured managed-service starter allowance. Managed Fly.io hosting becomes paid after the allowance and uses prepaid balance. Connecting the organization's own VPS has no Bunderhost hosting charge; the person still pays their server/provider separately. Read bunderhost://organization/context before promising a deployment: use billing.managedAllowed, hourlyRateCents and balanceCents rather than assuming every new account starts at zero or needs a top-up. If managedAllowed is false, explain the observed gate and give the returned topUpUrl. Do not invent a starter amount or expiry.

Ask whether the person has GitHub. Prefer a private repository because it preserves history, simplifies recovery, and enables automatic deploys and previews. If they have no account or one useful setup attempt fails, offer retrying GitHub or using a local ZIP, and explain that upload releases are manual, have no PR previews, and leave the local folder as the only source copy after the archive is deleted. A URL or provider machine state is not proof that an application is healthy: wait for a terminal deployment and call get_environment_health.

# Bunderhost documentation

The sections below are the documentation at /docs, word for word. A connected agent reads each one as the MCP resource bunderhost://docs/<section>.

# 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](#application-image).

## Three ways in

- **A GitHub repository.** Pushing deploys, pull requests get preview
  environments. Start from [New project](/projects/new).
- **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](/docs/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](#deploying) |
| Add system packages to the image | `Dockerfile.bunderhost` · `bunx bunderhost dockerfile` · [Application image](#application-image) |
| Run production on your own server | Organization → Servers · `bunx bunderhost target` · [Your own servers](#your-own-servers) |
| Set variables and secrets | Env tab · `bunx bunderhost env` · [Environment variables](#environment-variables) |
| Preview a pull request, add a domain | Previews, Domains · `bunx bunderhost domains` · [Previews and domains](#previews-and-domains) |
| Read logs, errors, performance | Logs, Errors, Performance tabs · `bunx bunderhost logs --runtime` · [Running in production](#running-in-production) |
| See how people use it, where they get stuck | Analytics tab · [Product analytics](#product-analytics) |
| Restore or download the database | Data tab · `bunx bunderhost db pull` · [Backups](#database-backups) |
| Browse data, files, jobs, users | Data, Storage, Background, Users tabs · [Application data](#application-data) |
| Let people sign in with Google or GitHub | Settings · `bunx bunderhost auth` · [Sign-in](#sign-in-with-google-and-github) |
| Send and receive email on your domain | Messaging tab · [Email](#email) |
| Let an agent do any of the above | [Agents and MCP](#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](/org/settings). 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](/projects/new) 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](#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](#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

```bash
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](#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](#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](#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:

```bash
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:

```bash
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:

```dockerfile
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:

  ```dockerfile
  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:

  ```dockerfile
  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](/org/settings). Bunderhost
shows one command to run on the server as root:

```bash
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](#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](#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](#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](#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](#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](#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](#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](#database-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](#a-database-on-the-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](#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:

```bash
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](#a-database-on-the-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:

```bash
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](#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](#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:

```js
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](#database-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](#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:

```json
{
  "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:

```bash
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](/docs/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](/org/settings),
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](https://developers.openai.com/plugins/build/mcp-events)
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.
