Configure

Configuration

Two files configure bay: .bay/config.toml for the repository and .bay/policy.toml for the checks.

bay is in development. These pages describe bay as it will ship.

`.bay/config.toml`

This file lives in the repository. It names trunk, the remote, the adapters, the executor timings, retention, and the update settings.

toml

# .bay/config.toml
trunk = "main"
remote = "origin"

[trailers]                         # map Intent and Actor to your own trailer keys
intent = "Intent"
actor = "Actor"

[check]
command = "scripts/bay-check"      # the check adapter

[notify]
command = "scripts/bay-notify"     # the notify adapter

[policy]
profile = "default"                # completion dimensions per change kind
evidence_reuse = "off"             # or "exact-inputs"

[hooks]
cache_max_age_s = 30               # older coordination cache: COVERAGE_UNKNOWN

[agent]
product = "claude"                 # leave this table out with no agent adapter

[executor]
command = "scripts/bay-executor"   # optional: an external executor (the executor contract)
submission_timeout_s = 120
execution_budget_s = 1800          # the default is 30 minutes
lease_s = 60                       # an owner silent this long may be replaced
heartbeat_s = 10
takeover_s = 120                   # default: twice the lease
publish_window_s = 60

[retention]
window_s = 604800                  # one week

[update]
auto = true                        # one background check a day at most
channel = "stable"                 # "stable" or "latest"
version = "=0.1.0"                 # optional pin: an exact version or a range

Key	Meaning
`trunk`	The name of the trunk branch.
`remote`	The Git remote that bay fetches from and pushes to.
`[trailers] intent`, `actor`	Your own trailer keys for Intent and Actor. The other bay trailers have fixed names.
`[check] command`	The check adapter.
`[notify] command`	The notify adapter. It gets one event and exits 0 when it delivered it.
`[policy] profile`	The completion dimensions per change kind.
`[policy] evidence_reuse`	`off`, or `exact-inputs` to reuse a pass only on matching inputs.
`[hooks] cache_max_age_s`	The oldest coordination cache the hook accepts. With an older cache, a write to a declared input gets `COVERAGE_UNKNOWN`.
`[agent] product`	The agent product adapter, for example `claude`. Leave the table out when the machine uses no agent adapter.
`[executor] command`	An external executor that follows the executor contract. Leave it out to use `bay executor run`.
`[executor] submission_timeout_s`	How long the executor's `submit` may take before the submission ends as timed out.
`[executor] execution_budget_s`	The time budget for the checks before landing. The default is 30 minutes.
`[executor] lease_s`	An owner whose chain does not move for this long may be replaced. The default is 60.
`[executor] heartbeat_s`	How often an owner renews its lease. The default is 10.
`[executor] takeover_s`	How long a change stays idle before another actor may adopt it. The default is twice the lease.
`[executor] publish_window_s`	Time added to the execution budget for the head of the queue. The default is 60.
`[retention] window_s`	How long a closed change keeps its drafts before the retention cut. The default is one week.
`[update] auto`	`false` turns off the daily background update check.
`[update] channel`	`stable` or `latest`.
`[update] version`	A pin: an exact version such as `=0.1.0`, or a range.

The acceptance policy lives on trunk at .bay/policy.toml. bay judges each candidate by the policy at its base, never by its own copy. Every policy change raises revision and lands as an ordinary checked change.

toml

# .bay/policy.toml (on trunk)
revision = 5                       # an integer; every policy change raises it

[[check]]
id = "tests"
environment = "linux-x86_64"
command = "scripts/bay-check tests"
adapter = ["scripts/bay-check", "scripts/bay-check.d/", "pytest.ini"]
inputs = []                        # inputs beyond the tree; "commit" keys evidence by commit
expected_minimum = 400             # required, no default
timeout_s = 1800
path = ["/usr/local/bin", "/usr/bin", "/bin"]   # absolute directories; the check's PATH
env = ["DATABASE_URL"]             # the only variables passed from the executor

[[quarantine]]                     # optional: one check set aside for a stated time
id = "tests"
environment = "linux-x86_64"
reason = "red on trunk since change k3m9p1; fix in progress"
end = "2026-10-25"                 # a date or a Change-Id

Key	Meaning
`revision`	An integer. Every policy change raises it.
`[[check]] id`	The check id.
`[[check]] environment`	The environment the check runs in. One check can be required on several environments.
`[[check]] command`	The command that runs the check. Its executable must be in `adapter`.
`[[check]] adapter`	Every path that computes the verdict: the command, its harness, and the runner configuration.
`[[check]] inputs`	Inputs beyond the tree. `commit` keys the evidence by commit, so a result for one commit never stands for another with the same tree.
`[[check]] expected_minimum`	Required, with no default. The least number of tests the check must collect.
`[[check]] path`	Absolute directories that make the check's `PATH`. A relative entry makes the policy invalid.
`[[check]] env`	The only variables the check gets from the executor. Their names enter the digest, never their values.
`[[quarantine]]`	One check set aside, with `id`, `environment`, `reason` and `end` (a date or a change id).
`[[check]] timeout_s`	The time limit of the check in seconds. Queue wait does not count.

Rules for checks

Each pair of id and environment appears only once.
The executable of command must be inside the adapter list.
A check that collects fewer tests than expected_minimum is unknown, never pass.
bay runs the adapter paths from the base, never from the candidate.
The check sandbox holds only the adapter paths and the candidate tree.
A read outside them fails the check as infra_failure.

The check's environment

A check starts with a fixed environment: PATH from path, HOME and TMPDIR in the sandbox, and LANG=C.UTF-8.
It also gets each variable that env names; a named variable the executor lacks is infra_failure.
A check that relied on an inherited variable must now declare it in env.

Set a broken check aside

Sometimes a required check is red on trunk itself, and it would block every change. Add a [[quarantine]] entry for it in a checked policy change. The entry names the check, a reason and an end. The landing result names the quarantine as a coverage gap, and bay status lists it. The change that fixes the check removes the entry. An entry past its end stays until a policy change removes it.

Keep required checks short

One trunk lands one change per required check run. So the length of your required checks sets how many changes land each day. Require a few fast checks before landing. Run the broad suite after landing, and order it by risk if you like. A red found after landing gets a fix, or bay undo.

Change a check or its adapter

A candidate that changes the policy or an adapter path must raise revision. bay checks that candidate twice: once with the base adapter, once with its new adapter. Both runs must pass every required check. As a last resort, a registry key can sign a repair of a broken adapter. That repair touches only .bay/policy.toml and adapter paths, and its new adapter must pass.

Configure

Configuration

Two files configure bay: .bay/config.toml for the repository and .bay/policy.toml for the checks.

bay is in development. These pages describe bay as it will ship.

`.bay/config.toml`

This file lives in the repository. It names trunk, the remote, the adapters, the executor timings, retention, and the update settings.

toml

# .bay/config.toml
trunk = "main"
remote = "origin"

[trailers]                         # map Intent and Actor to your own trailer keys
intent = "Intent"
actor = "Actor"

[check]
command = "scripts/bay-check"      # the check adapter

[notify]
command = "scripts/bay-notify"     # the notify adapter

[policy]
profile = "default"                # completion dimensions per change kind
evidence_reuse = "off"             # or "exact-inputs"

[hooks]
cache_max_age_s = 30               # older coordination cache: COVERAGE_UNKNOWN

[agent]
product = "claude"                 # leave this table out with no agent adapter

[executor]
command = "scripts/bay-executor"   # optional: an external executor (the executor contract)
submission_timeout_s = 120
execution_budget_s = 1800          # the default is 30 minutes
lease_s = 60                       # an owner silent this long may be replaced
heartbeat_s = 10
takeover_s = 120                   # default: twice the lease
publish_window_s = 60

[retention]
window_s = 604800                  # one week

[update]
auto = true                        # one background check a day at most
channel = "stable"                 # "stable" or "latest"
version = "=0.1.0"                 # optional pin: an exact version or a range

Key	Meaning
`trunk`	The name of the trunk branch.
`remote`	The Git remote that bay fetches from and pushes to.
`[trailers] intent`, `actor`	Your own trailer keys for Intent and Actor. The other bay trailers have fixed names.
`[check] command`	The check adapter.
`[notify] command`	The notify adapter. It gets one event and exits 0 when it delivered it.
`[policy] profile`	The completion dimensions per change kind.
`[policy] evidence_reuse`	`off`, or `exact-inputs` to reuse a pass only on matching inputs.
`[hooks] cache_max_age_s`	The oldest coordination cache the hook accepts. With an older cache, a write to a declared input gets `COVERAGE_UNKNOWN`.
`[agent] product`	The agent product adapter, for example `claude`. Leave the table out when the machine uses no agent adapter.
`[executor] command`	An external executor that follows the executor contract. Leave it out to use `bay executor run`.
`[executor] submission_timeout_s`	How long the executor's `submit` may take before the submission ends as timed out.
`[executor] execution_budget_s`	The time budget for the checks before landing. The default is 30 minutes.
`[executor] lease_s`	An owner whose chain does not move for this long may be replaced. The default is 60.
`[executor] heartbeat_s`	How often an owner renews its lease. The default is 10.
`[executor] takeover_s`	How long a change stays idle before another actor may adopt it. The default is twice the lease.
`[executor] publish_window_s`	Time added to the execution budget for the head of the queue. The default is 60.
`[retention] window_s`	How long a closed change keeps its drafts before the retention cut. The default is one week.
`[update] auto`	`false` turns off the daily background update check.
`[update] channel`	`stable` or `latest`.
`[update] version`	A pin: an exact version such as `=0.1.0`, or a range.

`.bay/policy.toml`

toml

# .bay/policy.toml (on trunk)
revision = 5                       # an integer; every policy change raises it

[[check]]
id = "tests"
environment = "linux-x86_64"
command = "scripts/bay-check tests"
adapter = ["scripts/bay-check", "scripts/bay-check.d/", "pytest.ini"]
inputs = []                        # inputs beyond the tree; "commit" keys evidence by commit
expected_minimum = 400             # required, no default
timeout_s = 1800
path = ["/usr/local/bin", "/usr/bin", "/bin"]   # absolute directories; the check's PATH
env = ["DATABASE_URL"]             # the only variables passed from the executor

[[quarantine]]                     # optional: one check set aside for a stated time
id = "tests"
environment = "linux-x86_64"
reason = "red on trunk since change k3m9p1; fix in progress"
end = "2026-10-25"                 # a date or a Change-Id

Key	Meaning
`revision`	An integer. Every policy change raises it.
`[[check]] id`	The check id.
`[[check]] environment`	The environment the check runs in. One check can be required on several environments.
`[[check]] command`	The command that runs the check. Its executable must be in `adapter`.
`[[check]] adapter`	Every path that computes the verdict: the command, its harness, and the runner configuration.
`[[check]] inputs`	Inputs beyond the tree. `commit` keys the evidence by commit, so a result for one commit never stands for another with the same tree.
`[[check]] expected_minimum`	Required, with no default. The least number of tests the check must collect.
`[[check]] path`	Absolute directories that make the check's `PATH`. A relative entry makes the policy invalid.
`[[check]] env`	The only variables the check gets from the executor. Their names enter the digest, never their values.
`[[quarantine]]`	One check set aside, with `id`, `environment`, `reason` and `end` (a date or a change id).
`[[check]] timeout_s`	The time limit of the check in seconds. Queue wait does not count.

Rules for checks

Each pair of id and environment appears only once.
The executable of command must be inside the adapter list.
A check that collects fewer tests than expected_minimum is unknown, never pass.
bay runs the adapter paths from the base, never from the candidate.
The check sandbox holds only the adapter paths and the candidate tree.
A read outside them fails the check as infra_failure.

The check's environment

A check starts with a fixed environment: PATH from path, HOME and TMPDIR in the sandbox, and LANG=C.UTF-8.
It also gets each variable that env names; a named variable the executor lacks is infra_failure.
A check that relied on an inherited variable must now declare it in env.