For agents

The page your agent reads to build and deploy your app. It is also served as plain Markdown.

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:

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:

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.