Reference
Build on bay
Build your own product or internal platform on bay's public contracts, the way tools build on Git.
bay is a tool, like Git, and anyone can build on it. A platform team can wrap it for many repositories. A tool maker can show its state in new screens. A hosting provider can serve repositories whose pushes bay judges. Each of them calls bay's commands, reads its results and plugs in through its plugins. bay stays one program for all of them, with nothing special for any one builder.
This page is a map. It names each contract and the page that holds it. bay has no server, no accounts and no screens. Those belong to your product.
When to use this page
- An internal platform: your team runs bay across many repositories and wants one view of them.
- A repository host: you serve main to others, and bay's hooks judge every push.
- A tool for agents or people: you show changes, refusals, locks and approvals in your own screens.
- A runner farm: you run checks and merges on your own machines, CI or containers.
The contracts
Each row names a contract, what a product does with it, and where these docs describe it. Read that page for the details. This table only points to it.
| Contract | What your product does with it | Where it lives |
|---|---|---|
bay.result/1 on stdout, with --json | Reads every outcome: decision, reason, allowed, retry_when and next_step. | Results and refusals: The result document |
bay help --json | Reads the commands, flags, reason codes, word list, agent hooks and result schema of the bay it runs. | Results and refusals: Read the contract from bay |
say and detail.words | Shows people bay's plain sentence, and keeps bay's inner words out of its own screens. | Results and refusals: The plain sentence |
bay host and its Git hooks | Serves main from a bare repository whose own hooks judge each push. | Host a main branch without a forge |
The key registry, refs/bay/registry, and bay enrol | Decides which agent, runner, producer, reviewer and approver keys count. | Keys and the registry |
[runner] command and bay runner run --once | Runs merges on its own machines, CI or containers. | Runners: The external runner contract |
bay status --since and detail.cursor | Follows merges and events after a cursor, and stores the cursor between reads. | See what your fleet is doing: Read what changed |
bay status --all | Reads the fleet map: machines, sessions, runners and red checks. | See what your fleet is doing: What the map shows |
[plugin.notify] and bay.event/1 | Gets each event the runner writes, once. bay status --since still lists one it lost. | See what your fleet is doing: Get notices |
[plugin.wake] and bay.wake/1 | Wakes an agent when a talk waits for it. | Talk to other agents: Wake the recipient |
[plugin.assets] and .bay-assets | Keeps large files in its own store, named by SHA-256 in Git. | Configuration: Keep large files out of Git |
Main's commit trailers: Change-Id, Actor, Open: | Shows who merged what, in the agent's own words, and what waits for a person. | Concepts: What main's commit says |
[locks] paths | Names files that never merge, so one session at a time edits each. bay status --all lists the locks held now in detail.locks. | Agents and hooks: Lock files that never merge |
bay waiting, bay approve and bay reject | Puts a person's yes or no in its own screens. | Require a person's approval |
bay evidence record | Records a review from its own system, signed with a reviewer key. | Wire any reviewer to bay |
detail.agents | Knows what bay judges in each agent product, and what it cannot see. | Agents and hooks: Read the hooks from bay |
bay plugin test | Runs bay's contract cases against each plugin it ships. | Configuration: Test a check or a plugin |
Host main and judge every push
Run bay host on the machine that serves your repositories. Its hooks are Git's own, set in the repository's config, so git receive-pack runs them on every push. SSH and Git's own HTTP backend both run that program, so both reach bay's hooks. Who may push at all stays with your product: SSH keys, tokens or file permissions. Until the host holds a key registry, it only keeps main moving forward. Create the registry before anyone else pushes, so the host also checks each push's signatures and scope.
bay host /srv/git/app.git --main mainRun runners where you like
A runner needs a clone, the checks' tools and, with a key registry, its own runner key. It can loop, or make one pass with --once whenever your product calls it, such as after a push. Read the pass's decision, and let retry_when say whether another pass can help. by_itself and after_wait can; after_person and after_fix wait for someone. A pass with no answer is unknown, and unknown is never success.
bay runner run --once --jsonGive people plain sentences
Show say as bay wrote it. It says what happened, then why, then one step. Its words never include a word that detail.words lists. Use the same list in your own screens, so a person meets one word for each idea.
bay help --json | jq '.detail.words[] | {word, say, avoid}'Read state through bay
bay status does not run in a bare repository, so keep a plain clone beside your host. Read state there with bay status --json. bay status --since <cursor> lists what happened after the cursor you stored. The cursor is opaque. After bay status, bay status --all lists each live session's agent, change and state. The records under refs/bay/* are bay's own. Read them through bay, not by parsing them.
bay status --since --json # the first read: take detail.cursor
bay status --since "$cursor" --json # every read after: what happened sinceStore large files through a plugin
An assets plugin is one program with put, get and exists. It can talk to any store you run: a folder, a bucket or your own service. bay hashes every file itself, so it never trusts the identity a store names. A change merges only when the store holds its bytes.
bay plugin test assets -- scripts/bay-assetsSign with the key registry
Give each agent, runner and producer its own key, and enrol only the public half. Keep the registry key with a person, for example on a hardware key. Then your product never holds a key that can add a key. A removed key stays out: bay enrol refuses it, and the host refuses a registry version that drops a removal.
bay enrol agent agent-7 agent-7.pubPin the bay you build on
bay's version numbers are 0.x, so a minor release can still change a command. The changelog names each change. Pin one exact version: BAY_VERSION at install, and bay.updateVersion for updates. Move the pin on purpose. After each move, read detail.commands from bay help --json, and run bay plugin test again. A consumer refuses a major schema version that it does not know.
curl -fsSL https://getbay.io/install.sh | BAY_VERSION=<version> shWhat bay does not do
- It runs no server and keeps no accounts.
- It has no web pages and no app. At a terminal, it prints plain sentences.
- It does not decide who may connect to push or clone. SSH, your Git server or your product does.
- It sends no telemetry, and your code goes only to your own Git remote.
- It has no build or option for one builder.
- What a product needs goes in its own config, plugins and docs.