How Boomship works

1. Sign in and open the workspace.
2. In Settings → Intelligence, choose Boomship Managed or add your own Anthropic, OpenAI, Google or OpenRouter key. Keys are encrypted with AES-256-GCM; only the last four characters are shown again.
3. Open a project from the titlebar. To give the Brain your code, add a GitHub token in Settings → GitHub and connect a repository.
4. Type an outcome into the composer and press Enter. Every step appears in the agent panel as it happens, and the run ends with a receipt.

Understand. The Context Compiler retrieves the smallest useful context from the Brain (vector and lexical search, import neighbours, files changed together, confirmed memories) and records why each item was included.

Build. The agent works in a runner with real tools: files, commands, tests and git. Every tool call is written to a ledger with hashes of its input and output.

Verify. A separate stage collects the diff itself, re-runs the checks and asks a different model to review. It does not trust the builder’s summary.

Receipt. Each check is passed, failed or not run, and confidence comes with its reason. Checkpoints are taken before and after, so a run can be undone as a whole.

Fast

Quick everyday work: the fastest connected model, low effort.

Auto

Boomship chooses the model and the effort for each task; planning and review escalate on their own.

Deep

More exploration and verification: a frontier model at full effort.

Swarm

Parallel approaches: the work is split into nodes that run side by side in their own worktrees, each verified, then merged.

Swarm runs persist their nodes. If one stops, Resume graph on its receipt reuses the merged nodes and re-runs the rest. Without a repository, nodes run one at a time in the shared workspace and the receipt says so.

Every run ends with a Work Receipt: files changed, what was inspected, each check’s state, the reviewers’ findings, cost and duration. A check that did not run is shown as not run, never left out.

tests

The project’s tests, re-run by the verifier in the workspace. Tests the import graph predicts for the change run first.

typecheck

tsc --noEmit in the workspace.

lint

The project’s linter, when it has one.

review

An independent model reviews the diff. It is never the model that built the change when another is eligible.

security

An adversarial security review of the diff. Required at high and critical risk.

secrets

A local scan of the added lines for credentials. git_commit refuses staged secrets.

critique

A visual critique of the preview, before and after, when UI files changed and a preview is loaded.

browser

A real Chromium pass over the preview.

Before a Deep or Swarm run, an acceptance contract states the objective, success conditions and non-goals. Risk comes from the contract and from the files the change touches and what depends on them. High and critical risk require the security review.

High

Tests passed on a fresh run, typecheck is clean, and an independent reviewer found no defects.

Medium

Tests passed, but the reviewer raised concerns or there was no review.

Low

A required check failed, or a check the risk level requires did not run.

Not verified

Nothing could be observed: no runner, a failed or cancelled run, or no change to verify.

Prove it re-runs verification against the workspace and writes a fresh receipt. Undo restores the checkpoint taken before the run.

<outcome>

Any sentence starts a Build run in the selected mode, for example “Add rate limiting to /api/run”.

/design <url|here> [brief]

A visual critique of a page against the Design Constitution. “here” uses the page loaded in Build’s Preview.

/break <url|here>

Try to break it: an adversarial browser pass (rapid clicks, empty inputs, duplicate submits, a phone viewport).

/verify <PR link> [--report]

Verify a GitHub pull request independently. With --report the verdict is posted as a “Boomship Verify” commit status.

/design and /break need Chromium on the host. When the host cannot run them, the composer says why instead of sending the request. Esc stops the run that is executing.

A chain is up to ten goals, one per line, that run in order in the current project. Each waits for the one before it to finish and meet its condition: is verified (high or medium confidence) or completes. The first can wait for a start time.

When a run does not meet its condition, everything behind it stops and says why. The queue is dispatched when a run finishes and on a one-minute tick in the server process, which needs a Node host.

One switch in Automate pauses everything automatic. The dispatcher holds ready runs, and webhook triggers answer 423 until it is turned back on.

A trigger queues its chain when a signed POST reaches its URL. The secret is shown once when you create the trigger and stored encrypted.

x-boomship-timestamp

Unix seconds. Must be within 5 minutes of the server’s clock.

x-boomship-signature

"sha256=" + hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`)).

x-boomship-delivery

Optional id. A delivery with the same id as the last accepted one is rejected.

SECRET='<your trigger secret>'
BODY='{"context":"optional text for the runs"}'
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')"
curl -X POST '<trigger url>' -H 'content-type: application/json' \
  -H "x-boomship-timestamp: $TS" -H "x-boomship-signature: $SIG" \
  -H "x-boomship-delivery: $(uuidgen)" -d "$BODY"

Bodies are capped at 64 KB, and a trigger fires at most once every 30 seconds. Until the signature verifies, every failure gets the same 401. After that: 403 disabled, 409 replayed delivery, 429 cooldown, 423 paused. The body’s context reaches the builder labelled as untrusted input. Event triggers from connected apps are not in this release.

Connected repositories are chunked by declaration, with symbols, import edges and recent git history. Search fuses vector and lexical results and says which retriever found each hit. Without an OpenAI key the Brain is lexical only, and says so.

Memories (decisions, rules, rejected approaches, bugs) carry a source, confidence and a state: confirmed, uncertain, stale or superseded. When a memory contradicts the code, the code wins.

A repository is fetched with the GitHub token of the person who connected it, and only on projects where that is safe.

/verify <PR link> fetches the pull request, resets it to its merge base so the diff is exactly the PR, installs dependencies with install scripts disabled, and runs the same verifier as a Build run, sandboxed. The result is a receipt. Add --report to post it as a commit status.

Every run has a permission scope and a budget for tokens, cost and time, charged on each model turn. Shipping (push, pull requests) is off unless you allow it in the composer’s scope chip. When a limit is reached the run stops, and the receipt says which limit stopped it.

With the Docker runner, commands and git run in a container. A repository’s git configuration that could execute code (hooks, fsmonitor, filters, includes and similar) is refused.

The boundaries in full, each with the file that holds it: Security.

Vercel serves the web half: pages, API routes, SSE and Supabase Realtime. The full engine (queue workers, the Automate tick, Chromium for /design and /break, the Docker runner) needs a Node host. The repository’s Dockerfile and docker-compose.prod.yml package it as one container plus Redis.

GET /api/health reports what the answering host can actually do: whether the database is reachable, the run mode, whether a worker is live, the runner, encryption and managed providers. It answers 503 when the database is not reachable.