Skip to the content.

One file configures a factory: bees.toml, in the root of a git clone of the project being built, or elsewhere with project.dir naming the clone (see [project] below). Without --template, bees init writes it with every option listed and the optional ones commented out at their default, so configuring is uncommenting and editing lines; see config templates for the alternative. bees config validate checks the file and bees config show [role] prints the settings each role ends up with.

The file starts with a version key, followed by these tables:

Table Purpose
[project] The git remote, repository, default branch and state directory
[filter] Which GitHub issues and pull requests the factory can see
[github] The GitHub account the factory acts as
[scheduler] Concurrency, polling, retries, budgets and the review loop
[logging] Console log format and level
[notes] Where a role’s notes live: files, or Neo4j Agent Memory
[global] Prompt, skills, MCP servers, profile selection and environment for every role
[roles.<name>] The same keys per role, plus a few that only one role takes
[profiles.<name>] Agent, model, effort and sandbox settings selected by [global] or a role

An unknown key anywhere in the file is a load error, so a typo cannot pass as a default. Every validation error names the key and what to change.

Durations are written the way Go reads them: "30s", "5m", "1h30m".

bees review reads none of this file. Its settings are ~/.config/bees/config.toml and the project’s context.toml, with defaults.toml below the first; Reviewing a pull request describes all three.

Jev review settings

Set OPENROUTER_API_KEY for the bees process to enable the optional Jev boost. With the variable unset or empty, reviews make no Jev request and add no record or log line. The factory uses agentcore’s default settings and one Judge per process across developer reviews, requested reviews and all project schedulers, including projects added or restarted through reload. A cooldown in one project applies to the others. There is no bees.toml key for Jev.

For bees review, put overrides in ~/.config/bees/config.toml:

[jev]
url = "https://openrouter.ai/api"
model = "~typesafe/jev-latest"
api_key_env = "OPENROUTER_API_KEY"
timeout = "10s"

These are the defaults. The factory does not read this table. url is an HTTP(S) base URL without credentials, query or fragment; the endpoint is <url>/v1/systemone. model is at most 128 characters without whitespace. api_key_env is an environment variable’s name, never its secret value. timeout bounds each request, must be positive and cannot exceed "1m". Unknown keys and invalid values fail with an error naming the key, even with the boost off.

Jev sees a guide, the brief’s change description, acceptance criteria, style rules and touched areas, changed-file paths and line counts, generated-file exclusions, reviewer-notes rules and complete findings. It never receives the diff, diff.patch or checkout file contents. Text quoted in findings is sent as written. The key goes only to the configured endpoint as a bearer credential.

Findings with a probability below 0.3 are removed; the rest reach triage or the factory’s judge session in descending probability order, preserving ties. jev.json in the review artifact records the outcome, fallback reason and detail, models, probabilities, kept and full eliminated findings, usage, request count, duration, version and threshold. The progress or factory log reports ranked and eliminated counts, or the fallback reason.

Invalid settings, oversized or rejected requests, timeouts, rate limits, outages, unusable responses, cooldowns and cancellation of the Jev request alone leave the unboosted list intact. A timeout or outage allows one retry. Cancelling the review itself retains ordinary cancellation handling. Reviewing a pull request describes context shortening, recording and shared cooldowns.

User-level profile defaults

Every project load also reads defaults.toml beside that review configuration: $XDG_CONFIG_HOME/bees/defaults.toml when XDG_CONFIG_HOME is an absolute path, otherwise ~/.config/bees/defaults.toml. The file is optional. It lets a machine with several projects define agent profiles, their role mappings and the GitHub account once:

version = 5

[profiles.fast]
agent = "claude"
model = "sonnet"
effort = "low"

[global]
profile = "fast"
profile_by_size = { xs = "fast", s = "fast" }

[roles.reviewer]
brief_profile = "fast"
angle_profiles = { docs = "fast" }
angles = { xs = ["quick_general"] }

[github]
login = "busybees[bot]"
app_id = 123456
private_key = "~/.config/bees/busybees.pem"

The file accepts only version, [profiles.<name>], global.profile, global.profile_by_size, every role’s profile and profile_by_size, the reviewer’s brief_profile, angle_profiles, judge_profile and angles, and [github] with every key it has in bees.toml. Any other key is an error. It has its own migration history, begins at the current version shown above, and must include that version.

The project bees.toml is the nearer layer and wins. A same-named profile in the project replaces the user profile whole. Map settings merge entry by entry: a project entry replaces the user entry for that size or angle, while the remaining user entries stay. [github] is one account and is taken whole or not at all: a project whose bees.toml has a [github] table takes nothing from the user one. An empty [github] table makes that project act as your own gh login. Validation happens after this merge, so the two files may refer to each other’s profiles; an error names the file that set the bad key. Invalid values and refused keys in defaults.toml are still errors even when the project would replace them.

bees config show names the file beside every value it took from defaults.toml, per entry for the map selectors, so a role running on a profile the project file never mentions says where both came from. See the config show section for the shape.

SIGHUP, the live view’s r key, and every other operation that reloads a project read both files again. A machine config itself does not inherit these defaults, but every project it lists does. bees review reads the same file below its own config.toml and takes the reviewer’s profiles and selectors, and [github], from it; Reviewing a pull request lists what it takes.

One bees process managing several projects reads a machine config instead, which lists the bees.toml of each project.

Machine config: several projects

A machine config is a separate file that lists the bees.toml files of the projects one bees process manages, and holds the settings that span them:

projects = [
  "~/src/foo/bees.toml",
  "../bar/bees.toml",
  "/srv/factories/baz.toml",
]
max_developers = 3
retention_period = "72h"

bees finds a machine config the same way it finds bees.toml: --config, then $BEES_CONFIG, then a file named bees.toml in the working directory or a parent. It reads the file’s keys to tell the two kinds apart: a file with a top-level projects key is a machine config. bees config validate checks either kind. A command that works on one project refuses a machine config with an error saying which kind of file it found.

You edit the file by hand. bees run --config /path/to/machine.toml runs every listed project. Add -d to detach; SIGHUP reloads the project list and every project’s bees.toml. See Running in the background.

version

version = 5

The format version of the file, not of bees. bees init writes the current one, 5. A file without the key is version 0.

Adding an optional key never bumps the version. Renaming or removing a key, or changing what one means, does, and the release notes of the bees version that bumps it say what changed.

A bees release can also start refusing a value it accepted before, without a migration. The file then fails to load with an error naming the key, because the value is yours and bees cannot guess the replacement. The MCP server name bees is one such value (see MCP servers).

[project]

Key Type Default Description
remote string "origin" Git remote the factory fetches from and pushes to. A name; spaces and / are rejected.
repo string derived GitHub repository as owner/name. Derived from the remote’s URL when unset (https, ssh:// and git@github.com: forms). Set it when the URL is not a github.com one.
default_branch string derived Branch developers branch from, reviewers diff against and QA tests. Read from the remote’s HEAD when unset.
state_dir string ".bees" Where mail, notes, session logs and scheduler state live. A relative path is resolved against the directory holding bees.toml. bees init adds it to .gitignore when it is inside the clone.
branch_prefix string "bees/" Prefix of developer branches: bees/issue-12.
dir string bees.toml’s directory The git clone the factory works in, when it differs from the directory holding bees.toml. A relative path is resolved against the directory holding bees.toml.

What the product is and how to build, test and run it are not configuration. Every role reads the repository’s own README, CONTRIBUTING, AGENTS.md and CLAUDE.md, and keeps what it learns in its notes file.

The main checkout is dir when set, else the clone holding bees.toml. Every session runs in a temporary git worktree cut from it, so remote has to point at the GitHub repository.

[filter]

The filter decides which issues and pull requests the factory sees and touches. Configured criteria are ANDed, and everything the factory creates stays visible: it is made to match label, assignee and milestone, and the account the factory acts as always passes creator.

Key Type Default Description
label string "bees" The factory’s label. It is the base name of every workflow label (bees:triage, bees:ready, …) and, while require_label is true, the visibility gate. Spaces and colons are rejected.
require_label bool true With false, assignee, milestone and/or creator alone decide visibility. The factory still puts label on everything it creates.
assignee string "" Only see items assigned to this GitHub login. "@me" is resolved to the machine’s own gh login at startup, even with [github] set. Everything the factory creates is assigned to this login so it stays visible.
milestone string "" Only see items in this milestone, by title. Also the milestone for issues the factory creates when neither --parent nor --related gives one, and the one put on the pull requests it opens. People manage milestones; bees inherit them, or pick among them for the features of an agreed design.
creator string "" Only see items opened by this GitHub login or by the account the factory acts as (github.login, else your own gh login). An issue or pull request the factory opens is authored by that account, so it is visible whatever creator says.

require_label = false without assignee, milestone or creator is rejected: it would make every open issue in the repository visible.

A factory acting as a GitHub App that should pick up only the issues one person files, plus the ones it opens itself:

[filter]
creator = "kyle"
[github]
login = "busybees[bot]"
app_id = 123456
private_key = "~/.config/bees/busybees.pem"

One person running busybees for their share of a team repository needs no special label on the issues:

[filter]
label = "kyle-bees"     # still the base of the kyle-bees:* labels
require_label = false
assignee = "@me"

An issue assigned to you with no state label and neither kyle-bees:feature nor kyle-bees:feedback gets kyle-bees and kyle-bees:feedback on first sight and goes to the product manager as feedback; label it kyle-bees:triage or kyle-bees:ready yourself to have it built. Because every label carries the prefix, two people can run two factories in one repository with two labels.

Workflow labels

Every label is derived from filter.label, shown here for bees. bees init and bees labels sync create them in GitHub.

Label Meaning
bees Visible to the factory
bees:feature Feature issue owned by the product manager, which makes it detailed enough and breaks it into work items. Outside the state machine
bees:bug Bug work item, filed by a developer, the reviewer, QA or a person. It says what the issue is, not where it goes
bees:feedback Feature idea, product feedback or bug report for the product manager. Outside the state machine
bees:question The product manager is waiting for a person to answer on a feature or feedback issue; removed by the orchestrator when they reply
bees:proposal A feature issue a bee wrote. It sits next to bees:feature, and a person removes it to approve the breakdown
bees:planning A person and the product manager are still agreeing a feature or feedback issue; the product manager discusses and breaks nothing down. Not a state label; only a person sets or removes it. See Planning with the product manager
bees:planned A person ended planning: the scope is agreed and the product manager breaks the issue down on its next run. Not a state label; only a person sets or removes it
bees:priority A person wants this next: dispatched before the rest of the bees:ready queue. Not a state label. People set it; the project manager may add it to a work item that unblocks the factory itself, and the product manager carries one from a feedback issue onto the work item it creates from it
bees:review-requested On a pull request, not an issue: a person asks the reviewer for one review pass, whoever opened the pull request. Not a state label; the orchestrator removes it as the review starts. See Asking for a review of any pull request
bees:triage Needs refinement by the project manager
bees:ready Detailed enough for a developer
bees:in-progress A developer worker owns it
bees:blocked Waiting on an answer to a question
bees:review Pull request open and under review
bees:approved Reviewer approved; waiting for a person to merge
bees:needs-human The factory gave up, or a person is holding the issue. A person may add it on top of another state label to hold the issue where it is; it wins while it is there

An issue also carries at most one size label, independent of its state. The project manager sets it when it moves a work item to bees:ready, and the orchestrator adds bees:size/m to a ready issue that has none. See Sizing.

Label Meaning
bees:size/xs One file, obvious change, no design
bees:size/s A few files, clear approach, existing tests cover it
bees:size/m A feature slice across several packages, needs new tests
bees:size/l Crosses subsystems or needs a design decision
bees:size/xl Too big for one pull request; split it instead

[github]

With the table unset, the factory acts as whatever account the machine’s gh is logged in with, and everything it writes on GitHub looks like it came from the person running it. [github] gives the factory an account of its own: a GitHub App, which GitHub shows as a bot on everything the factory writes.

[github]
login = "busybees[bot]"
app_id = 123456
private_key = "~/.config/bees/busybees.pem"
git_name = "busybees[bot]"
git_email = "234567+busybees[bot]@users.noreply.github.com"
Key Type Default Description
login string "" The account the factory acts as. For a GitHub App it is the App’s slug followed by [bot]. bees init and bees doctor check it against the credential, bees status reports it, and the orchestrator reads every comment that login posts as the factory’s own.
app_id int 0 The GitHub App’s ID, from its settings page. Set with private_key.
private_key string "" The GitHub App’s private key: the path of the .pem file GitHub generated (~ is your home directory), a "$VAR" or "${VAR}" reference to a variable holding the PEM, or the PEM itself. bees reads it when it starts. A reference that expands to nothing, or a file it cannot read, fails the start with the key named.
token string "" In place of app_id and private_key, a token for login, passed as GH_TOKEN to every gh call the orchestrator makes and to every session. A "$VAR" or "${VAR}" value is read from the environment bees runs in. A reference that expands to nothing is a load error naming the variable.
git_name string "" Author and committer name for the commits developer sessions make (GIT_AUTHOR_NAME, GIT_COMMITTER_NAME).
git_email string "" Author and committer email for those commits (GIT_AUTHOR_EMAIL, GIT_COMMITTER_EMAIL).

login goes with either app_id and private_key or token, and bees refuses any other combination. To share one App across projects, put the table in defaults.toml instead: a project with no [github] table of its own takes it whole, and so does bees review. git_name and git_email are an identity rather than a credential, so each may be set alone, and whichever is unset leaves that half of the commit identity to the machine’s own git configuration.

Setting up the GitHub App

  1. On GitHub, open Settings → Developer settings → GitHub Apps → New GitHub App. The name you give it becomes its slug, the last part of https://github.com/apps/<slug>. Any homepage URL will do. Clear Webhook → Active: bees polls and needs no webhook.
  2. Under Repository permissions, set:

    Permission Access
    Contents Read and write
    Issues Read and write
    Pull requests Read and write
    Checks Read-only
    Commit statuses Read-only
    Workflows Read and write, only if developers may change files under .github/workflows

    Metadata is read-only and always granted. Issues cover labels, comments, milestones and sub-issues.

  3. Create the App. On its settings page, copy the App ID into app_id, then Generate a private key. GitHub downloads a .pem file: move it somewhere only you can read, such as ~/.config/bees/, and point private_key at it.
  4. Install App, on the account that owns the repository, with access to the repository project.repo names.
  5. Set login to the slug followed by [bot]. For commits GitHub attributes to the App, set git_name to the same login and git_email to <id>+<login>@users.noreply.github.com, with the id from gh api 'users/busybees[bot]' --jq .id.

bees init checks the App before the factory uses it: GitHub accepts the App ID and key, login is the App’s, the App is installed on the repository, and a token it mints can read the repository. bees doctor asks the same questions, and two more: that the App can write an issue and that it can push a branch.

Tokens

The bees process that runs sessions holds the private key, and no session does. From it, bees mints the App’s installation tokens, each restricted to project.repo and good for an hour. It mints one when it first needs one, and the next only once that one has two minutes left, however many calls come in between.

Sessions never get the key. A session with gh and git access gets the App’s gh first on its PATH and a git credential helper, both of which read the current token from <state_dir>/github/token. When that token has expired, they ask the bees process that started the session for a new one and wait for it, so a session that runs for hours keeps working. The same goes for the bees commands a session runs. This works the same way on the host and in a container or sbx sandbox, which mount the state directory.

A session with sandbox = "none" can read any file your user can, the .pem included. To keep the key out of its reach, hold it in a variable instead, which no session is given:

private_key = "$BEES_GITHUB_APP_KEY"
export BEES_GITHUB_APP_KEY="$(cat ~/.config/bees/busybees.pem)"

The tokens reach only project.repo, so leave scheduler.report_factory_errors off with a GitHub App: the reports go to kpenfound/busybees.

A token

token in place of app_id and private_key makes the factory act as the account the token belongs to, and login is that account’s login. Use a fine-grained personal access token scoped to the one repository: read and write on Issues, Pull requests and Contents, read on Metadata. A classic token with the repo scope also works. With scheduler.report_factory_errors on, the token also needs issue write on kpenfound/busybees.

bees init checks the token before the factory uses it: GitHub accepts it, it belongs to login, and it can read the repository. bees doctor asks the same questions, and whether the account can write an issue and push a branch. Repository access does not imply either. A fine-grained token’s permissions sit on top of the repository role, so a token can read the repository as an admin and still be refused every label edit or every push.

A session runs with GH_TOKEN set to the token and git configured to answer https pushes through gh auth git-credential. When token is a "$VAR" reference the session is also given that variable, holding the resolved token, because the bees commands a session runs load bees.toml themselves. It goes into the session’s environment and never into a file.

What the account covers

The account covers everything the factory does on GitHub: polling, label edits, review requests, the escalation comment, bees init’s label creation, bees doctor’s checks, bees issue, the built-in MCP tools, and a session’s own gh pr create, gh api and git push. With git_name and git_email set, its commits are the factory’s as well.

Your own credential helper is reset for a session’s pushes, so it cannot answer them, and your stored credentials are neither read nor written. The helper only steers https remotes: on an ssh:// or git@github.com: remote the commits are the factory’s but the push authenticates with the machine’s ssh key. The full list of what a session is given is under Exported into every session.

Comments the factory posts still end with the comment marker, because [github] is optional and with it unset every comment arrives under your own login. With it set, the orchestrator reads a comment as the factory’s when it carries the marker or when login wrote it, so the escalation comment, which carries no marker, is not mistaken for a person’s. People mention a GitHub App as @busybees, by its slug, and the factory reads that as a mention of busybees[bot].

filter.assignee = "@me" still means you. It says whose work the factory picks up, and is resolved with the machine’s own gh login before any token is used, in the orchestrator, the MCP server and bees doctor alike. GitHub does not assign issues to a GitHub App, so leave filter.assignee unset or name a person.

[scheduler]

Key Type Default Description
poll_interval duration "5m" How often GitHub is polled. A poll costs two API calls (gh issue list, gh pr list); see API budget. Also the minimum gap between two runs of one singleton role.
rate_limit_backoff duration "15m" How long to pause polling after a poll fails with a GitHub rate-limit error, instead of retrying after poll_interval. Also how long the whole factory pauses when a session hits the claude session limit and no usable reset time came with it; see The claude session limit.
max_developers int 1 Concurrent developer workers. Each owns one issue and runs its developer, reviewer and checks stages one after another, so reviewer concurrency follows developer concurrency. 0 means the default; a negative value is rejected.
max_review_rounds int 3 Developer and reviewer rounds before an issue is escalated with bees:needs-human. 0 means the default; a negative value is rejected.
retries int 1 Extra attempts a session gets after failing for infrastructure reasons: it timed out, ran out of turns, hit an API error or rate limit, or the agent crashed. A session that ran and reported with bees done, failed included, is not retried, and neither is one that hit the claude session limit. 0 disables retrying; 0 to 5. See Escalation.
retry_delay duration "10m" Wait before a retry. "0s" retries at once; a negative value is rejected.
retry_with_fallback bool true Run the retry on the profile the role’s resolved profile names as its fallback, agent included; a second retry runs on that profile’s own fallback, and so on down the chain. A profile without one reruns as it was.
triage_batch_size int 5 Most issues handed to the project manager in one session. 0 means the default.
notes_consolidate_every int 10 Sessions a role runs between two in which it is also asked to consolidate its notes. 0 means the default; a negative value is rejected.
notes_max_bytes int 32768 Ask for consolidation early, whatever the session count, once a role’s notes are larger than this. Measured in the backend notes.backend names. 0 means the default; a negative value is rejected.
dispatch_order string "small-first" Which bees:ready issue a free developer takes next: small-first, oldest or large-first. Ties go to the older issue, and an issue without a size ranks as m. Issues carrying bees:priority come first whatever this says, and issues already in flight (bees:in-progress, bees:review, a bees:ready issue with an open pull request, a bees:approved issue whose checks were interrupted) are resumed before new work. See Sizing.
max_large_in_flight int 1 How many bees:size/l issues developer workers may hold at once. A large issue over the cap is skipped and the worker takes the next issue that fits. 0 means no cap; a negative value is rejected.
pr_fix_conflicts bool true Hand an open pull request that conflicts with the default branch back to its developer: the developer is mailed from orchestrator to merge, resolve, test and push, and an approved issue goes back to bees:ready ahead of new work. See Conflicts with the default branch.
pr_keep_updated bool false Do the same when a pull request is merely behind the default branch.
stacked_prs bool false Build a blocked_by chain of work items under the same feature as a stack of branches and pull requests, each depending on its predecessor’s, instead of independently. false keeps every work item branching from the default branch on its own, as it does today. See Stacked features.
review_assigned_prs bool false Ask the reviewer for one pass over every open pull request in the filter whose head branch does not start with project.branch_prefix, without waiting for bees:review-requested. With filter.assignee set, that is the pull requests assigned to the factory. A new push to one earns another review. See Asking for a review of any pull request.
report_factory_errors bool false Let a role record a draft issue about an error the factory itself caused: a tool that misbehaved, a prompt that contradicted the code, an orchestrator mislabel it had to work around. The report_factory_error tool writes the draft, scrubbed by the role of repository names, tokens, paths and people, to <state_dir>/feedback/<id>.json, and every full pass files the queue against the busybees repository: a report that looks like an issue already there is a comment on it, one that looks like nothing is a new issue with no label and no assignee. Off, the tool records nothing, says so, and nothing is filed.
feature_proposals bool true A feature issue a bee creates is a proposal: it carries bees:proposal and a person approves it by removing the label. false lets a bee break its own features down without a person’s approval: bees issue create --feature writes no bees:proposal, and --parent and bees issue link do not refuse a parent for carrying one. See Feature issues.
notify string list [] GitHub logins and org/team slugs the factory turns to when it needs a person. No leading @, at most one /. See Notifying a person.
product_manager_interval duration "1h" Minimum time between product manager runs. Unread mail in its inbox starts one earlier.
qa_interval duration "30m" Minimum time between QA runs. QA runs when something was merged since its last run (the first run always happens); mail in its inbox starts one earlier. The merged-PR query runs at most once per interval.
max_cost_per_issue float 0 USD one work item may cost across every session run for it. 0 is unlimited; a negative value is rejected. See Cost budgets.
max_cost_per_day float 0 USD the whole factory may spend over a rolling 24 hours. 0 is unlimited; a negative value is rejected.
max_cost_per_day_resume_percent float 100 How far the rolling 24 hours has to fall back before dispatch starts again, as a percentage of max_cost_per_day: at 80 a factory paused at $100.00 stays paused until the window is under $80.00, rather than resuming at $99.99 and going straight over again. 100 (the default) resumes as soon as the window is under budget, 0 means that default, and a value outside 0-100 is rejected. See Cost budgets.
max_cost_per_session float 0 USD one session may cost. 0 is unlimited; a negative value is rejected.
keep_workspaces bool false Leave temporary worktrees on disk after a session, for debugging.
workspace_root string "" Directory temporary worktrees are created under. Empty means bees under the system temp directory.
retention_period duration "24h" How long the state directory keeps data after it goes stale: the session directories and issues/work-<hash>.json of a closed issue, counted from its pull request merging or, without one, the issue closing, and ledger.jsonl lines older than this, never within the last 24 hours, which max_cost_per_day reads. Retention is always on: zero or a negative value is rejected. Unset, the machine config’s retention_period applies when there is one.
work_hours string "" Daily window during which GitHub is polled every poll_interval, as "HH:MM-HH:MM" on a 24-hour clock. Empty polls around the clock, and the three keys below are ignored. See Work hours.
off_hours_poll_interval duration "1h", or poll_interval when that is longer How often GitHub is polled outside work_hours. Must be at least poll_interval.
work_days string list ["mon","tue","wed","thu","fri"] Days the window applies to, as lowercase three-letter names from mon to sun. At least one, and each must be a known day.
timezone string "" IANA name the window is read in, such as "America/New_York". Empty means the machine’s local time.

Notifying a person

By default the factory and the people it works for share one GitHub account, so nothing it writes notifies anybody: you wrote the comment, and GitHub sends no mail for your own. notify says who to reach:

[scheduler]
notify = ["kpenfound", "myorg/bees-team"]

The review request is best effort: a failure is logged and the pull request still reaches bees:approved. GitHub refuses to request a review from a pull request’s own author, and with a shared account the configured login usually is the author, so a login often gets the mention and not the request. Teams are always accepted; list one if you want the request too.

Work hours

Most polling exists to notice what people did: new issues, feedback, reviews, merges. Outside working hours that is rare, so work_hours polls GitHub less often then:

[scheduler]
poll_interval = "5m"            # inside the window
off_hours_poll_interval = "1h"  # outside it
work_hours = "09:00-18:00"
work_days = ["mon", "tue", "wed", "thu", "fri"]
timezone = "America/New_York"

Only the GitHub polling cadence changes. The scheduler still ticks every poll_interval, and a finished session wakes it in between; a tick that is not due for a poll runs a local pass over the last poll’s issue and PR lists (see The scheduler loop). Everything driven by the local mailbox, which is the developer and reviewer loop, the checks stage and an answered question moving bees:blocked back to bees:ready, runs at full speed at every hour. bees tick and bees exec ignore the window.

The poll before the window opens is scheduled for the moment it opens, so the first poll of the day is at 09:00, not an interval later.

A rate limit never speeds polling up. After a rate-limited poll the next one is due after the longer of rate_limit_backoff and the interval in force, so off hours with off_hours_poll_interval = "8h" that is 8h.

A window whose start is later than its end wraps midnight and belongs to the day its start falls on: "22:00-06:00" with work_days = ["fri"] covers Friday 22:00 through Saturday 06:00 and nothing else. A window whose start equals its end is rejected, as is a window that is not "HH:MM-HH:MM", an unknown or empty work_days, a timezone the zoneinfo database does not know, and an off_hours_poll_interval shorter than poll_interval.

bees status prints a work hours: line either way, with the cadence in force and when the next poll is due. See bees status.

API budget

The orchestrator is frugal with the GitHub API, because the sessions call gh freely on top of it:

What Cost When
A poll 2 calls (gh issue list, gh pr list) every poll_interval, or every off_hours_poll_interval outside work_hours
Human PR feedback 3 calls per PR (reviews, review comments, comments) only for PRs whose updatedAt moved since the last look
Human issue comments 1 call per issue only for issues whose updatedAt moved since the last look: bees:in-progress, bees:review, bees:approved and bees:blocked unconditionally, and, once [github] names an account to mention, bees:triage, bees:ready, bees:feature and bees:feedback too, to look for an @-mention. A pass with no [github] login configured, or one that sees an issue with no recorded time, records the time and fetches nothing
Product-manager has-work check 1 issue view per feedback or feature issue only for issues whose updatedAt is newer than the last product manager run. Noticing that a feature’s sub-issues have all closed costs nothing: it compares the numbers recorded on the last run with what the poll found open
Product-manager run 1 issue view per open feedback or feature issue, 1 REST call per open feature (sub-issue progress) and 1 GraphQL call per open work item (parent feature) every run
Planning mode 1 extra issue view per bees:planned issue the has-work check did not already fetch every product manager run while an issue is agreed and not yet acted on
QA merged-PR check 1 call at most once per qa_interval
Checks 1 call per poll of a checks stage, 2 when the branch requires no check every roles.reviewer.checks_poll_interval while waiting
Visibility backstop 2 list calls after every session
Refreshing what a session changed 1 issue view per issue after a session, for each issue it created or relabelled through the MCP server; none when it changed no issue
The marker audit 1 comment read per issue or pull request after a session, for its issue, the pull request it was given or opened, and each issue it changed, only with [github] set, and nothing at all without it
Parent feature lookup 1 GraphQL call per triage item, per open work item and per developer session per project manager run, product manager run, developer session
bees issue create --parent 3 calls (parent details, create, attach as sub-issue); --related 2; plain 1 whenever a role files an issue
Worker stage transitions a few issue view, pr view and issue edit calls per transition

An idle factory costs two calls per poll. When GitHub does rate-limit the process, polling pauses for rate_limit_backoff and tries again.

What the factory spends on Anthropic is a separate budget, capped by the three max_cost_* keys.

Cost budgets

All three budgets are 0 by default, which is unlimited. They are spent against the session ledger, the numbers bees cost reports, so a retried session counts like any other:

[scheduler]
max_cost_per_issue = 25.00   # every session run for one work item
max_cost_per_day = 100.00    # whole factory, rolling 24 hours
max_cost_per_session = 10.00 # a single session

A running session is never interrupted on cost. Each budget is enforced at the first moment the factory can act on it:

Budgets are money, not turns: max_turns already caps how long one session may go on.

The ledger is read fail-closed. A session whose agent reported no cost (a codex session, or one killed before its result event) is entered with cost_unknown set: it counts as a session, adds nothing to the dollars, and while the last 24 hours hold one the budget’s log line, bees status and the live view say how many the sum leaves out (“daily budget: $42.10 / $100.00, 2 sessions of unknown cost”). A ledger line that does not parse anywhere but at its end fails every read of the ledger with the file and the line, and that, with max_cost_per_day set, pauses dispatch like a budget reached: nothing the daily budget gates starts until the ledger reads again, and bees status shows paused: ledger unreadable: <file> line <n> does not parse. With max_cost_per_issue set, an issue whose spend has to be seeded from the ledger at that moment is escalated the same way an issue over the budget is, with the escalation naming the line. With neither set the line fails bees cost and the today: line of bees status alone. Remove or repair the line to resume; a torn final line, what a crash mid-write leaves, is ignored. See bees cost.

The claude session limit

Every role shares one Anthropic account, so when one session runs out of capacity the whole factory has. claude reports it two ways and either counts: a rate_limit_event in the session’s stream whose status is neither allowed nor allowed_warning, or, from a session that failed without reporting an outcome, a result text naming a session or usage limit (“You’ve hit your session limit · resets 11:50pm (America/Detroit)”). The text is only read this way when the session reported nothing, because it is the session’s own prose.

A session that ends that way is not retried, since every attempt would hit the same wall, and its issue is not escalated, since the limit says nothing about the work: the issue keeps its state label and is picked up afterwards. The scheduler pauses all dispatch, developers and singletons alike, until the limit resets. Running sessions finish on their own, and polling and label reconciliation carry on.

The pause lasts until the reset time the event carried, with two limits: a reset that is missing or already past falls back to rate_limit_backoff, and one more than 8 hours ahead is clamped to 8 hours. The pause is logged when it starts and when it lifts, and bees status names the time it lifts. It is held in memory only, so restarting bees run clears it and the first session re-learns the limit.

[logging]

[logging]
format = "text"   # text | json
level = "info"    # debug | info | warn | error
Key Type Default Description
format string "text" Console log format: text or json.
level string "info" Console log level: debug, info, warn or error.

Logging is a property of the bees process, so the table is top-level and applies to every command. It is the lowest-priority source: a flag beats an environment variable, which beats bees.toml, which beats the default. So bees run --log-format text gives a readable terminal in a project whose file says json, and -v wins over level = "info".

Commands that never read bees.toml, such as bees version and bees done, and any command run against a file that fails to load, use the flag, environment and default settings only.

There is no quiet key. --quiet is a shorthand for one invocation; level = "warn" is the service-shaped equivalent, and it also drops the one-line session summaries that --quiet keeps.

bees run in a terminal draws the live view instead of logging and silences console logging while it is up; --no-tui, a redirected stdout and every other command log as this table says. The bees.log file in the state directory is not configurable: it gets every record at debug level, in JSON. See bees run.

[notes]

[notes]
backend = "file"   # file | neo4j
# neo4j_url = "https://memory.neo4jlabs.com/v1"
# neo4j_api_key = "$BEES_NEO4J_API_KEY"
Key Type Default Description
backend string "file" Where the notes_read and notes_write tools keep a role’s notes: file (the state directory) or neo4j (Neo4j Agent Memory).
neo4j_url string "" The base URL of the Neo4j Agent Memory REST API, including its version segment: the hosted service’s (https://memory.neo4jlabs.com/v1) or a self-hosted deployment’s. Required, and must be an http(s) URL, with backend = "neo4j".
neo4j_api_key string "" An API key for neo4j_url, written as a "$VAR" reference so the secret is not in this file. Required with backend = "neo4j"; a reference that expands to nothing fails to load, naming the variable. Redacted as written in bees config show.

bees neither runs nor embeds Neo4j Agent Memory; with backend = "neo4j" the notes tools talk to the REST API at neo4j_url, and so do bees status and the scheduler consolidation trigger when they measure a role’s notes. neo4j_url and neo4j_api_key are ignored with backend = "file", so they can stay in the file across a switch. bees notes show|edit|reset|add are the exception: they always act on the state directory’s file, whatever backend is.

[global] and [roles.<name>]

[global] and each [roles.<name>] table take the same keys. The role name is one of product_manager, project_manager, developer, reviewer, qa, release_manager. The CLI accepts aliases such as pm, dev and release; the TOML keys do not. release_manager is disabled by default. Explicitly opt in before using it because it can publish a GitHub release:

[roles.release_manager]
enabled = true
Key Type Default Description
prompt string "" Text appended to the role’s built-in prompt.
prompt_file string "" Path, relative to bees.toml, whose contents are appended after prompt. The file must exist when the file loads.
skills string list [] Skills by git URL. See Skills.
pi_packages string list [] Pi packages a pi session loads with pi -e on top of pi-mcp-adapter, which it always loads: npm:<name>[@version], git:<repo>[@ref], a URL, or a path (a relative one from the session’s worktree). [global] and role lists are unioned. Sessions of other agents ignore it. An empty entry, one starting with - and one naming pi-mcp-adapter are load errors. See Pi.
skills_refresh string "24h" [global] only. How stale a skill clone may get before it is pulled when a session needs it: never, always or a duration.
mcp.<name> table   MCP servers keyed by name. See MCP servers.
profile string "" Profile name. Under [global], the default profile for every role; under a role, that role’s profile override. An empty value uses the implicit built-in profile.
profile_by_size table {} Profile name per work item size, keyed by xs, s, m, l or xl. Accepted under [global] and every role.
max_turns int 200 Agentic turns per session (claude --max-turns). 0 means the default. Codex, opencode and pi have no such limit and a codex, opencode or pi role ignores it.
timeout duration "45m" Wall-clock limit for one session; the session’s process group is killed when it expires. "0s" means the default.
allowed_tools string list [] Passed as claude --allowedTools. A codex, opencode or pi role ignores it.
disallowed_tools string list [] Passed as claude --disallowedTools. A codex, opencode or pi role ignores it.
shell string the shell bees runs under Exported into sessions as $SHELL. Claude Code discovers its Bash tool’s shell from $SHELL, so this is the lever, without being a guarantee. Must be an existing file.
sandbox_image string "" The image a container session runs in: it must hold the role’s agent, git and gh. A container role without one or container_use_environment is refused at bees run. See The container mode. For an sbx session it is the sandbox’s template instead, an image built on sbx’s image for the agent (docker/sandbox-templates:claude-code, :codex or :opencode); empty selects sbx’s own. See The sbx mode.
container_use_environment string "" Path, relative to the project repository root, to a dagger/container-use environment definition to build the container profile’s image from, instead of sandbox_image. Requires the resolved profile’s sandbox = "container" and is a load error together with sandbox_image on the same resolved role. See Building from container-use.
sandbox_dagger_engine string "" The host’s Dagger engine an sbx session is given, unix://<socket path>, tcp://<host>:<port> or docker-container://<container name>, with the Dagger CLI installed in the sandbox. Empty gives neither. Requires the resolved profile’s sandbox = "sbx" at every size and sandbox_dagger_version. See Dagger in the sandbox.
sandbox_dagger_version string "" The Dagger CLI release installed in the sandbox for sandbox_dagger_engine, the engine’s own, such as "v0.20.5". Requires sandbox_dagger_engine.
env table {} Environment variables exported into every session: the agent, its shell tool and git see them, and so do MCP servers under claude, opencode and pi (codex starts a server with only the variables its entry names). A $VAR value is expanded from the bees process environment when the session starts. A name may not be empty or contain = or a space. See Exported into every session for how it meets the variables bees sets itself.
enabled bool true (false for release_manager) Roles only. false takes a role out of the rotation. release_manager must be explicitly enabled because it can publish a GitHub release. Disabling reviewer makes a developer’s pull request count as approved the moment it is opened, and with auto_merge it goes straight to the checks stage. Under [global] the key is an error. A named set of these decisions is a config template.

[profiles.<name>]

A profile bundles the agent, model, fallback, effort and sandbox for a session. Profiles are named globally, then selected by [global] or a role. Values omitted from a profile use its built-in defaults; a profile configured for codex, opencode or pi has no default model. fallback names the profile a retry runs on instead after a session on this one failed: that profile’s agent, model, effort and sandbox, which can be a different agent entirely.

[global]
profile = "bar"

[profiles.foo]
agent = "claude"
model = "fable"
fallback = "bar"
effort = "max"
sandbox = "claude"

[profiles.bar]
agent = "opencode"
model = "ollama/qwen3.8:27b-mlx"
effort = "high"

[roles.developer]
profile = "foo"
profile_by_size = { xs = "bar", s = "bar", l = "foo", xl = "foo" }
Key Type Default Description
agent string "claude" CLI a session runs as: claude (claude -p), codex (codex app-server), opencode or pi (pi -p, see Pi). An unknown value is a load error. See Running a session.
model string "opus" for claude, "" otherwise Model alias or full id, passed to the selected agent (provider/model for opencode and pi). An empty value lets codex, opencode or pi use its own configured model.
fallback string "" The profile a retry runs on instead, agent included: a session that failed for infrastructure reasons (a timeout, exhausted turns, a crash, a rate limit) is retried on it when scheduler.retry_with_fallback is on, the next retry on that profile’s own fallback, and so on; a brief or angle review session refused for want of capacity runs again on it. Must name a profile; a profile that names itself, or a longer cycle (a → b → a), is a load error. When both profiles run claude, the fallback’s model is also passed as claude --fallback-model, so claude switches to it within a session; codex and opencode have no such flag, and a fallback on another agent is a new session. A fallback in a sandbox other than sbx runs without the role’s Dagger engine.
effort string "" Passed as claude --effort when set: low, medium, high or max. Codex receives it as model_reasoning_effort; max maps to high. Opencode receives it as the default build agent’s variant; variants are names the model defines, not levels. Pi receives it as --thinking.
sandbox string "none" How much of the machine a session can reach: none, claude, container or sbx. A pi profile runs with none or container: any other mode is a load error. See Sandboxing.

The effective profile follows this order for a work item size: role profile_by_size[size], role profile, global profile_by_size[size], global profile, then the implicit built-in profile. An unknown profile name or size is a load error.

[roles.reviewer] only: checks and auto-merge

The reviewer owns the checks and the merge. These keys are accepted only under [roles.reviewer]; under [global] or another role they are a load error.

Key Type Default Description
auto_merge bool false Merge a pull request the reviewer approved once its checks are green. Off means people merge. A named set of these decisions is a config template.
merge_method string "squash" squash, merge or rebase (gh pr merge --<method> --delete-branch).
checks_wait duration "1m" Wait after approval before polling the checks, because some take a moment to report they started.
checks_poll_interval duration "2m" How often the checks are polled while waiting. One API call each, two when the branch requires nothing.
checks_timeout duration "30m" How long to wait for the checks before escalating with bees:needs-human.
max_check_fix_rounds int 2 Rounds of the reviewer diagnosing and the developer fixing a failed check before escalating.
pre_review_checks bool true Read the pull request’s checks before the first review, so the reviewer starts from a green pull request or is told it is not. Independent of auto_merge.
pre_review_checks_timeout duration "10m" How long that pre-review read waits for pending checks before reviewing anyway.
[roles.reviewer]
auto_merge = true
merge_method = "squash"
checks_timeout = "20m"

With pre_review_checks on, a developer worker reads the pull request’s checks once, between opening it and the first review: checks_wait, then a poll every checks_poll_interval, bounded by pre_review_checks_timeout. Green, and the review starts with the checks listed in the reviewer’s prompt. A failure goes to the reviewer in checks mode and then to the developer for a fix round first, sharing max_check_fix_rounds with the post-approval stage, and the review happens once the pull request is green. Still pending at the timeout, no check reported at all, or a read that fails, and the review happens anyway with the reviewer told nothing was verified. Later review rounds go straight to the reviewer with no second read. bees status shows the worker in the pre-review checks stage while it waits.

With auto_merge on, after approval the worker waits checks_wait and polls the checks every checks_poll_interval. All green merges. A failing check gets the reviewer a checks-mode session to find the main error and mail it to the developer, who pushes a fix, and the checks are polled again, up to max_check_fix_rounds. Still pending at checks_timeout, or a merge GitHub refuses (branch protection that needs a human review, say), escalates with bees:needs-human. See Merging.

Which checks are the gate: the required checks (gh pr checks --required) whenever the default branch requires any, and only those. A repository with no branch protection requires nothing, and gating on nothing would merge with nothing green, so there every check the pull request reports is the gate: a failing one blocks and a pending one is waited for. To take a check out of the gate, mark the ones that must block as required in the default branch’s protection rules; bees never reads those rules to change them. With no check reported at all, it merges after two consecutive empty polls and logs that no check was reported. bees doctor says which of the three is in force, and bees status shows it in the worker stage (checks (required), checks (reported), checks (none)).

[roles.reviewer] only: the review pipeline

The reviewer’s review runs a brief, then one session per angle, then a judge that merges what they found; these keys choose angles and execution profiles for each step. Like the checks keys, they are accepted only under [roles.reviewer].

Key Type Default Description
angles.<size> string list the built-in list for that size The angles a pull request of that size is reviewed from. <size> is xs, s, m, l or xl; one or more of quick_general, general, docs, test_coverage, acceptance_criteria, side_effects. An unknown size or angle, or an empty list, is a load error. A size this does not name keeps the built-in list.
brief_profile profile name size-resolved reviewer profile Execution profile for the brief. Its agent is one the review sessions can run as (claude, codex, opencode or pi); sandbox is ignored.
angle_profiles.<angle> profile name size-resolved reviewer profile Execution profile for that angle. Same agent rule as brief_profile, and its whole fallback chain with it. Unknown profile or angle names fail loading with the complete key path.
judge_profile profile name size-resolved reviewer profile All five execution fields, including sandbox, for the reviewer session that posts findings and decides the verdict.
Size Built-in angles
xs, s quick_general, docs
m, l general, docs, test_coverage, acceptance_criteria
xl general, docs, test_coverage, acceptance_criteria, side_effects

Phase overrides resolve through [profiles.*] after ordinary role and profile_by_size selection. An unspecified angle uses the size-resolved reviewer profile. Brief and angle sessions select agent, model, fallback and effort, subject to backend support (Codex maps max effort to high). They ignore the profile’s sandbox and run under the shared restricted execution’s read-only floor: no commands, writes, web/network tools, inherited MCP, factory identity, or writable or shared VCS access. Claude, codex, opencode and pi are the supported host agents, on every profile of the fallback chain too: a brief or angle session refused for want of capacity runs again as its fallback, under the same policy, and a chain that reaches an agent a review session cannot run as is a load error.

The judge applies all five profile fields, including sandbox, through an ordinary factory reviewer session. Its prompt, tools, permissions and ability to post the verdict belong to the reviewer workflow. Profiles contain no prompts, MCP, skills, environment, sandbox image, container environment, shell, timeout, turn limit or VCS settings; those remain role/phase-owned.

An angle that fails is named in the judge’s task and the rest are judged; a review where the brief or every angle failed escalates the issue instead. The standalone bees review configuration is a separate file: it takes the same [profiles.*] tables, selected by top-level brief_profile, angle_profiles and judge_profile; see Review configuration.

[profiles.review_quick]
agent = "claude"
model = "haiku"
effort = "low"

[profiles.review_judge]
agent = "claude"
model = "sonnet"
sandbox = "claude"

[roles.reviewer]
angles.xs = ["quick_general"]
brief_profile = "review_quick"
angle_profiles.docs = "review_quick"
judge_profile = "review_judge"

See Review pipeline for what each angle looks at.

[roles.product_manager] only: minimum issue size

This key describes the product manager, so it is accepted only under [roles.product_manager].

Key Type Default Description
min_issue_size string "" The smallest work item the product manager aims for when it breaks a feature down: xs, s, m, l or xl. Unset, it splits at whatever boundaries the work has. See Sizing.
[roles.product_manager]
min_issue_size = "m"    # fewer, larger work items per feature

It is a hint on the split, not a rule: nothing checks the size of an issue that gets created, and the project manager still sizes a work item as it finds it during triage. Work that is genuinely smaller still gets its own issue, whoever files it, so a bug found mid-implementation is unaffected.

[roles.developer] only: commit flags and max size

These keys describe the developer, so they are accepted only under [roles.developer].

Key Type Default Description
commit_flags string "" Extra flags for every git commit the developer makes, appended to its prompt verbatim.
max_size string "l" The largest work item a developer takes: xs, s, m, l or xl. A bees:ready issue sized above it is moved back to bees:triage for the project manager to split; the project manager is told the limit. See Sizing.
[roles.developer]
commit_flags = "--gpg-sign --signoff"
max_size = "m"          # anything bigger goes back to triage to be split

Signing (--gpg-sign, -S) happens inside a headless session on the machine running bees, so a signing key and agent must work for that user without a prompt. --signoff needs user.name and user.email, as any commit does.

[roles.developer] only: best of N

Best of N runs several developer sessions on the same issue, each on its own branch, and has an assembler session pick the pull request that goes to review. It is off until a size names a count.

Key Type Default Description
best_of_n_by_size table {} Attempts per work item size, keyed by xs, s, m, l, xl. An unknown key, or a value below 1, is a load error. A size with no entry, and an issue with no size label, gets one attempt.
best_of_n_model string "" The model every attempt runs when a size fans out. Empty: an attempt resolves its model the way a single session does, through its selected profile_by_size or profile.
best_of_n_prompt string "" The prompt every attempt runs with. Empty: the developer’s own prompt.
assembler_model string "" The model the assembler session runs. Empty: the developer’s resolved profile model.
assembler_prompt string "" The prompt the assembler session runs with. Empty: the developer’s own prompt.
[roles.developer]
best_of_n_by_size = { l = 3 }   # three attempts on a large issue

best_of_n_prompt = """
Do not read the other attempts. Solve the issue your own way.
"""

An entry of 1 is one attempt, the same as leaving the size out, so a table that names no size above 1 is best of N off. A size above 1 runs that many developer sessions at once for the issue’s first round, each on the branch <branch_prefix>issue-<n>-attempt-<i> and each in a max_developers slot of its own, so the count is clamped to max_developers. When every attempt has ended, one assembler session runs on the issue’s own branch with the attempt branches listed in its task, puts the result there (one attempt as it stands, or a synthesis) and opens the pull request from it, which goes to review as any developer’s does; the attempt branches are then deleted. An attempt that pushed no commits is listed as not a candidate; when none did, the issue is handed to a person, bees:needs-human.

[roles.developer] only: mixture of experts

A mixture of experts runs several developer sessions on the same issue, each one to a brief of its own, and has an assembler session combine their work into the pull request that goes to review. It is off until a size names its experts.

Key Type Default Description
moe_experts_by_size table {} The experts a work item of that size fans out to, keyed by xs, s, m, l, xl, each an ordered list of names from moe_experts. An unknown size, an empty list, a name moe_experts does not define, or a size that is also in best_of_n_by_size, is a load error. A size with no entry, and an issue with no size label, runs a plain developer round.
moe_experts table {} The experts themselves, one sub-table per name. prompt is what that expert’s session runs with in place of the developer’s own prompt, model the model it runs. Both are optional: an expert that names neither runs the developer’s prompt and resolves its model the way a single session does, through its selected profile_by_size or profile.
moe_assembler_model string "" The model the assembler session runs. Empty: the developer’s resolved profile model.
moe_assembler_prompt string "" The prompt the assembler session runs with. Empty: the developer’s own prompt.
[roles.developer]
moe_experts_by_size = { xl = ["backend", "frontend"] }
moe_assembler_model = "opus"

[roles.developer.moe_experts.backend]
prompt = """
Solve it in the server code.
"""
model = "opus"

[roles.developer.moe_experts.frontend]
prompt = """
Solve it in the interface.
"""

A size that names two or more experts runs that many developer sessions at once for the issue’s first develop round, one per name and in the order the list gives them: expert i works on the branch <branch_prefix>issue-<n>-attempt-<i>, with that expert’s prompt and model, in a max_developers slot of its own, so the count is clamped to max_developers and the experts past the clamp do not run. A size that names a single expert runs the plain developer session that leaving the size out would run, so that expert’s prompt and model go unused.

When every expert has ended, one assembler session runs on the issue’s own branch. Its task lists each expert branch and the expert it came from; it combines their work into one implementation on that branch and opens the pull request from it, which goes to review as any developer’s does. The expert branches are then deleted. An expert that pushed no commits is listed as not a candidate; when none did, the issue is handed to a person, bees:needs-human.

Sandboxing

sandbox in a profile says how much of the machine a session can reach. Select different profiles when roles that run untrusted code need a harder box than roles that only read the repository:

[profiles.unboxed]
sandbox = "none"

[profiles.boxed]
sandbox = "container"

[roles.developer]
profile = "boxed"
Mode What a session can reach
none Everything the user running bees can: the home directory, credentials, the network and every other checkout on the machine.
claude Claude Code’s own sandbox: writes to the worktree and the state directory, network to GitHub. See The claude mode and Security.
container A container holding the worktree, the repository’s .git and the state directory, and nothing else of the host. See The container mode and Security.
sbx A Docker Sandbox: a microVM holding the same three directories and nothing else of the host, its network held to the sbx policy, the agent’s credential injected by the sbx proxy. See The sbx mode and Security.

none is the default. bees run checks before it starts that every role in the rotation can have the box it asks for (the programs a claude box needs on Linux, an agent that runs under it, a container role’s image, credentials and engine, and an sbx role’s CLI and GitHub credential) and refuses to start while one cannot, naming the role: a factory that fell back to running that role unboxed would give it exactly what it was configured to be kept away from. bees exec and bees tick refuse the same session for the same reason.

bees config show prints the resolved mode per role, and bees status the mode of the session each worker is running right now.

See Security for what each mode protects and what it does not, filesystem, network and credentials in turn, including what a sandboxed session’s own GitHub credentials mean for it.

The claude mode

A session in claude mode runs under Claude Code’s sandbox, with a settings block bees writes for it. Every shell command, and every process it starts, runs inside a box the operating system enforces: Seatbelt on macOS, bubblewrap on Linux. The built-in file and web tools run in the claude process itself, outside that box, so Claude Code’s permission rules hold them to the same boundary, and anything those rules would ask a person about is refused instead.

What the session can reach:

On macOS nothing needs installing. On Linux the box needs bubblewrap and socat on PATH, which bees run checks before it starts. The box is Claude Code’s, so a role whose resolved profile’s agent is codex or opencode cannot use it: bees run refuses to start, naming the role. A profile with agent = "pi" and sandbox = "claude" does not load. Commit signing through gpg does not work inside the box, because gpg writes under ~/.gnupg.

To widen the box for one project, commit a .claude/settings.json to the repository: Claude Code merges its sandbox lists with the ones bees writes. A Go project on macOS needs its build cache and module proxy, for example:

{
  "sandbox": {
    "filesystem": { "allowWrite": ["~/Library/Caches/go-build"] },
    "network": { "allowedDomains": ["proxy.golang.org", "sum.golang.org"] }
  }
}

The settings of the user running bees (~/.claude/settings.json) merge the same way, and an excludedCommands entry there runs that command outside the box.

The container mode

A container session is the agent’s command line, unchanged, run inside docker run. It needs docker on PATH with a daemon that answers, and the image sandbox_image names on the machine: pull or build it yourself, bees never pulls. bees run checks all three ahead of the doctor, whatever --skip-doctor says, and refuses to start naming the role that fails. A role with container_use_environment instead of sandbox_image has its image built at session start, and docker build pulls the definition’s base_image then; see Building from container-use.

The container sees three things of the host, each bind-mounted at its host path so every path in the prompts and the environment means the same inside: the worktree, the repository’s .git (a linked worktree’s .git file points into it, and commits write there) and the state directory (mail, notes, the session directory). A role with skills also gets the skills cache, read-only. Nothing else: no home directory, no other checkout, no credential store. The session runs as the user running bees (claude refuses to skip permissions as root), with a HOME of its own on a tmpfs that is gone when the session ends; a settings directory baked into the image is reached by setting CLAUDE_CONFIG_DIR in the role’s env.

Its environment is built from nothing rather than from the one bees runs in, and holds, in this order: the agent’s credential forwarded from the bees environment when it is set there, the role’s env (which may name the credential itself), SHELL, the BEES_* variables, the [github] token and git identity, the git configuration every session runs with plus safe.directory = * and an insteadOf that pushes an ssh remote over https (the container has no ssh keys), and HOME. Values reach the engine by variable name, never on a command line. A container role therefore needs [github] (or GH_TOKEN in its env) and a credential for its agent; bees run refuses the role without them, because inside the container there is no other gh login and no keychain.

The credential is the agent’s own: ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN for claude, OPENAI_API_KEY or CODEX_API_KEY for codex, and for opencode and pi the key of whichever provider the model names. opencode reads ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, XAI_API_KEY and DEEPSEEK_API_KEY; pi’s keys are listed under Pi. Every one of them that is set is forwarded.

The bees binary is not in the container. The built-in MCP server runs on the host as bees mcp serve --listen, with the environment a session on the host would have started it with, and the session reaches it over HTTP at host.docker.internal with a bearer token of its own, passed through the container environment. The backend configuration references that variable; the token value stays out of configuration files and command arguments. The tools work unchanged; the session’s prompt does not offer the bees commands. A stdio MCP server configured in bees.toml starts inside the container, so its command must be in the image; a remote one is reached as configured (host.docker.internal reaches a server on the host).

The image must hold the agent, git and gh. A Dockerfile that does:

FROM node:22-bookworm
RUN apt-get update \
    && apt-get install -y --no-install-recommends git curl ca-certificates \
    && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
       -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
    && echo "deb [arch=$(dpkg --print-architecture) \
       signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] \
       https://cli.github.com/packages stable main" \
       > /etc/apt/sources.list.d/github-cli.list \
    && apt-get update && apt-get install -y --no-install-recommends gh \
    && rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code

A role that runs the product (QA, most often) names an image carrying the product’s toolchain too, under [roles.qa].

While the session runs, <session>/container-id holds the container’s id and <session>/mcp-server-pid the pid of the built-in MCP server bees started on the host for it, and the container is named bees-<session>-<random> and labelled bees.session=<session directory>, so docker ps --filter label=bees.session lists a factory’s sessions. Stopping the session (its timeout, or bees run stopping) removes the container. So does stopping it from outside: bees kill and the live view’s k key find a container session through that label and remove its container, which is what stops the agent: it runs in the container, not on the host, and killing the docker run client alone leaves it running. They stop the MCP server too, from its pid file: it runs on the host in a process group of its own, so a crash that takes bees down would otherwise leave it holding its port and serving the factory’s tools.

What the box holds: the session cannot read or write anything of the host outside the three mounts, and cannot reach the host’s credentials or its other checkouts. What it does not: the session has the network, the bot’s GitHub token, the Neo4j Agent Memory API key with the neo4j notes backend, its agent credential, and everything in the image; and the mounted state directory holds every role’s mail and notes, not only its own. On Linux the container runs as the user running bees so what it writes stays theirs, and reaches the host at the docker bridge gateway; the mode has been exercised on macOS with Docker Desktop.

Building from container-use

sandbox_image is the way to run a container session: point it at an image you built and published yourself, and bees runs it unchanged. This is a niche opt-in for a project that already keeps a declarative, buildable environment definition in the dagger/container-use format, and would rather bees build from that than from a hand-built image. Most projects should keep using sandbox_image instead.

Setting container_use_environment to a path builds the image from <path>/.container-use/environment.json in the project repository, at session start, instead of requiring sandbox_image. bees reads only that file’s format: it does not depend on container-use’s Go package, the Dagger SDK, or a running Dagger engine. Of the definition’s fields, bees uses:

workdir, secrets and services are read and ignored, without an error. The container always runs at the worktree’s host path regardless of workdir. secrets names Dagger secret-provider URIs bees has no pipeline to resolve, and services describes more than one container, which the sandbox does not support.

The built image must still hold the agent, git and gh, the same requirement a hand-built sandbox_image has. Providing them is the definition’s setup_commands/install_commands job. The image is tagged after a hash of the resolved build inputs (base_image, env, setup_commands, install_commands, in that order), so a definition whose formatting changes but whose build inputs do not reuses the image already built for it, and a change to any of those inputs builds a new one. docker build runs once per definition, the first time a session needs it. A missing or malformed environment.json, or a failing build, fails that session with an error naming the path or the build command, not a bees.toml load error.

The sbx mode

An sbx session is the agent’s command line, unchanged, run inside a Docker Sandbox: a microVM with its own kernel, filesystem, Docker daemon and network, which the sbx CLI creates and removes. It needs sbx on PATH and signed in (sbx login), and runs claude, codex and opencode; sbx has no template for pi, and a pi profile with sandbox = "sbx" does not load. bees run checks that sbx answers ahead of the doctor, whatever --skip-doctor says, and bees doctor reports it when a role uses the mode.

The sandbox is given the same three directories a container is, as its workspaces, each mounted at its host path: the worktree, the repository’s .git and the state directory (mail, notes, the session directory), and the skills cache read-only for a role with skills. Nothing else of the host: the shared skills store sbx mounts by default is switched off. The session runs as the sandbox’s own user, with the sandbox’s own home directory, and inside it the agent has sudo, package managers and a private Docker daemon: everything it installs stays in the sandbox, which is removed when the session ends.

[profiles.sandboxed]
agent = "codex"
sandbox = "sbx"

[roles.developer]
profile = "sandboxed"
sandbox_image = "ghcr.io/acme/widgets-sbx-codex:1"   # optional template

The sandbox is created for the role’s agent (sbx create <agent>), from sbx’s own template for it unless sandbox_image names one. sbx’s own is the -docker variant of the agent’s image below, which adds the private Docker daemon:

Agent Image Credential to store once
claude docker/sandbox-templates:claude-code sbx secret set anthropic
codex docker/sandbox-templates:codex sbx secret set openai (--oauth for a ChatGPT sign-in)
opencode docker/sandbox-templates:opencode sbx secret set <provider> for each provider its model uses (anthropic, openai, google, …)

sandbox_image is passed as sbx create --template: an image built FROM the agent’s image in that table, or its -docker variant to keep the Docker daemon, with the product’s toolchain added. sbx requires a template built for the agent it runs. sbx’s own templates hold the agent, git and gh. container_use_environment is a load error alongside sbx.

Its environment is built from nothing and holds the role’s env, SHELL, the BEES_* variables, the [github] token and git identity, and the git configuration every session runs with plus safe.directory = * and the https insteadOf. Values reach sbx by variable name, never on a command line. The agent’s own credential is not forwarded: store it once with sbx secret set, as the table says, and the sandbox’s proxy injects it into the agent’s requests without the value entering the sandbox. An sbx role therefore needs [github] (or GH_TOKEN in its env), because inside the sandbox gh and git push have no other credentials, and no agent credential in the bees environment; bees run refuses the role without the former. Do not also store a github secret with sbx secret set: the proxy would replace the bot’s token with it on every request to GitHub. The sandbox does not read the operator’s ~/.codex or ~/.config/opencode; bees passes a session’s MCP servers and settings on the command line (codex) or in the session’s own opencode.json (opencode), as it does on the host.

The bees binary is not in the sandbox. The built-in MCP server runs on the host as bees mcp serve --listen on the loopback, and the session reaches it over HTTP at host.docker.internal with a bearer token of its own, the way a container session does. The sandbox’s proxy forwards that name to the host’s localhost and checks it against the network policy, which denies it unless a rule allows it. Bees adds that rule for each session, once the sandbox exists and the server has its port, and removes it before it removes the sandbox:

sbx policy allow network --sandbox <sandbox> localhost:<port>
sbx policy rm network --sandbox <sandbox> --resource localhost:<port> --force

The rule names one sandbox and one port, so no other sandbox reaches the server and the session reaches nothing else on the host’s loopback. If sbx refuses the rule, the session does not start and bees removes the sandbox. You do not need a global localhost rule; see Security. The same policy decides which other hosts the session reaches: the Balanced preset allows GitHub and the AI provider APIs; add a module proxy or a package registry with sbx policy allow network. A stdio MCP server configured in bees.toml starts inside the sandbox, so its command must be in the template; a remote one is reached as configured, and sbx mcp add registrations are not used.

Written to the sbx CLI reference and not run for this page: the sandbox is created with sbx create --no-progress --name <session> --skills off <agent>, the command runs through sbx exec --interactive --workdir <worktree> --env <name>... with the prompt on stdin, and sbx rm --force removes the sandbox when the session ends, or when sbx create fails, since sbx can fail after it has made the sandbox. <session>/sandbox-name holds the sandbox’s name while it exists. bees kill does not remove a sandbox a crash left behind; sbx rm --force <name> does.

Dagger in the sandbox

sandbox_dagger_engine gives an sbx session the host’s Dagger engine, and sandbox_dagger_version the Dagger CLI release installed in the sandbox to reach it, so that a developer session can run dagger check. It is off unless set, and valid only when the role’s resolved profile, at every size, selects sbx; one key without the other is a load error. A fallback or judge_profile that selects another sandbox loads, and its sessions run without the Dagger CLI or the engine.

[roles.developer]
profile = "sandboxed"
sandbox_dagger_engine = "unix:///run/dagger/engine.sock"
sandbox_dagger_version = "v0.20.5"

The engine is one bees can reach on this machine:

The engine must be running and of sandbox_dagger_version’s release: the Dagger CLI refuses an engine it is not compatible with. Start one on a socket, for example:

docker run -d --name dagger-engine --privileged \
  -v /run/dagger:/run/dagger registry.dagger.io/engine:v0.20.5 \
  --addr unix:///run/dagger/engine.sock

On macOS the socket stays inside Docker Desktop’s VM. Give the container instead, sandbox_dagger_engine = "docker-container://dagger-engine", or publish a TCP port (-p 127.0.0.1:1234:1234 and --addr tcp://0.0.0.0:1234) and set sandbox_dagger_engine = "tcp://127.0.0.1:1234".

Once the sandbox exists, bees runs dagger version in it. When the sandbox’s template reports the role’s release (v0.20.5 and 0.20.5 match), the CLI is used as it is. Otherwise, the CLI missing, another release or the probe failing, bees installs the CLI into /usr/local/bin with the install script at https://dl.dagger.io/dagger/install.sh, as root, before the agent starts; the sbx network policy must allow dl.dagger.io. A failed install fails the session and removes the sandbox. To skip the install, give the role a sandbox_image that has the CLI on its PATH at the role’s release.

The session reaches the engine through _EXPERIMENTAL_DAGGER_RUNNER_HOST, which bees sets to the address above. For an engine on the host’s loopback, through the socket forward or on TCP, bees adds a rule allowing that port for the session’s sandbox, the same way it does for the built-in server. An engine on another host needs a rule of your own.

This widens what a session reaches: the engine runs containers outside the sandbox, with the engine’s own network and cache, not the sandbox’s policy. See Security. Written to the sbx CLI and Dagger references and not run for this page.

How global and role settings merge

Setting Rule
prompt, prompt_file Concatenated, separated by blank lines: global prompt, global prompt_file, role prompt, role prompt_file. The result is appended to the role’s built-in prompt under an “Additional instructions from bees.toml” heading, followed by the repository’s project prompt files.
skills Union, global first, order kept, duplicates dropped.
mcp Union by name; a role server replaces a global one of the same name.
env Union by name; the role wins.
max_turns, timeout, shell, sandbox_image, container_use_environment, sandbox_dagger_engine, sandbox_dagger_version Role value if set, else global, else the built-in default.
profile, profile_by_size For a work item size: role profile_by_size[size], role profile, global profile_by_size[size], global profile, then the implicit built-in profile.
allowed_tools, disallowed_tools Global list followed by the role list.
enabled Role only.
skills_refresh Global only.
min_issue_size roles.product_manager only.
commit_flags, max_size, best_of_n_by_size, best_of_n_model, best_of_n_prompt, assembler_model, assembler_prompt, moe_experts_by_size, moe_experts, moe_assembler_model, moe_assembler_prompt roles.developer only.
auto_merge, merge_method, checks_wait, checks_poll_interval, checks_timeout, max_check_fix_rounds, pre_review_checks, pre_review_checks_timeout, angles, brief_profile, angle_profiles, judge_profile roles.reviewer only. bees config show reviewer prints the resolved policy.

bees config show <role> prints the result.

Only the contents of prompt_file are re-read for every session. Everything else, prompt included, comes from the bees.toml and user-level profile defaults that bees run loaded when it started or last reloaded: r in the live view, or SIGHUP, reads both files again and the next session dispatched runs on it; a few keys, listed there, take a restart. The built-in role prompts are compiled into the bees binary and need a rebuild as well as a restart. bees status names the build the running scheduler was started from, and bees doctor warns when that build is behind the commit the repository has checked out.

Project prompt files

A project can keep role instructions in the repository instead of in bees.toml, so they are versioned and reviewed like code, and a branch can carry its own.

bees/prompts/common.md            every role
bees/prompts/developer.md         the developer
bees/prompts/product_manager.md   the product manager

bees/prompts/common.md is appended to every role’s prompt and bees/prompts/<role>.md to that role’s. Nothing is configured; a repository without the directory renders the prompt it would render anyway. The sources land on the built-in prompt in this order, each under a heading naming where it came from, so a bees.toml override still wins over what the repository says:

  1. [global] prompt and prompt_file
  2. [roles.<name>] prompt and prompt_file
  3. bees/prompts/common.md
  4. bees/prompts/<role>.md

The directory is bees/, without a dot. bees init adds /.bees/ to .gitignore, so files under .bees/prompts/ would be untracked, the opposite of instructions reviewed like code.

Sessions read the files from their own worktree at session start, so a session sees the files on the branch it is working on, and an edit takes effect on the next session with no rebuild and no restart. bees prompts show <role> --rendered has no worktree and reads the main checkout (project.dir, else the checkout bees.toml sits in); it says so when it finds any.

A file bees cannot use, unreadable or larger than 64 KiB, never stops a session: the session warns, skips that file and runs with the rest. bees doctor fails on such a file, and on a file no role reads (a misspelled name such as bees/prompts/develloper.md).

Anyone who can land a commit on a branch can change what the sessions on that branch are told to do. That is the point of the feature, and it is the same trust boundary as a CI configuration in the repository: review changes to bees/prompts/ as you would review a workflow file.

Skills

Skills are referenced by git URL and cloned into a cache directory, ~/.cache/bees/repos on Linux (~/Library/Caches/bees/repos on macOS) unless BEES_CACHE_DIR says otherwise. They reach Claude Code as plugin directories (claude --plugin-dir), so the worktree is never modified. Skills in the repository’s .claude/skills/ and in ~/.claude/skills/ are available without being listed.

skills = [
  "https://github.com/acme/skills",                 # whole repository
  "https://github.com/acme/skills#skills/tdd",      # one directory inside it
  "https://github.com/acme/my-plugin@v1.2.0",       # pinned tag or branch
  "git@github.com:acme/private-skills.git",         # ssh works too
]

The URL is <git-url>[@<ref>][#<sub/dir>]. The selected directory is one of three layouts, checked in this order:

  1. A Claude Code plugin, with .claude-plugin/plugin.json. Used as-is.
  2. A single skill, with SKILL.md at its root. Wrapped in a generated plugin exposing that skill.
  3. A skills collection, with a skills/ directory. Wrapped in a generated plugin exposing every skill in it.

Anything else is an error. Clones and wrappers are reused; a wrapper is rebuilt only when it is missing or its #sub/dir changed, because a session may be running with it.

A clone is pulled (git pull --ff-only) when a session needs it and it was last fetched more than skills_refresh ago, 24h by default. "always" pulls before every session, "never" never pulls. A failed pull is logged as a warning and never stops a session; a reference pinned with @tag is a detached checkout and cannot be pulled, which is the point of pinning.

bees skills list shows the cache and bees skills update pulls everything now, whatever the policy says.

MCP servers

A claude session is given the servers in a per-session --mcp-config file loaded with --strict-mcp-config, so it sees the servers configured here plus the built-in one, and none of your own. A codex session is given the same servers as -c mcp_servers.<name>.<key>=<value> overrides on its command line, next to whatever ~/.codex/config.toml configures. Codex filters a stdio server’s inherited environment. Bees forwards the built-in server’s GitHub credentials and configured notes API key through env_vars, which names variables to read from the session’s environment. Their values stay out of the generated MCP configuration and command arguments. Configured servers receive their entry’s env values. An opencode session is given the same servers as the mcp table of a per-session opencode.json, handed to it through OPENCODE_CONFIG, next to whatever its global configuration and the project’s own opencode.json name. A pi session is given the same servers in a per-session pi-mcp.json that pi-mcp-adapter reads alone; see Pi.

bees is reserved. Every session gets a server called bees carrying the factory’s own tools; see bees mcp serve. It needs no configuration and cannot be turned off. Defining [global.mcp.bees] or [roles.<role>.mcp.bees] fails to load with mcp server name "bees" is reserved for the built-in server.

Key Description
type stdio, http or sse. Defaults to stdio when command is set, http when only url is.
command Executable of a stdio server.
args Arguments for command.
env Environment of the server process. $VAR and ${VAR} are expanded from the bees process environment.
url Endpoint of an http or sse server.
headers HTTP headers for a remote server; $VAR expansion applies.

Either command or url is required.

[global.mcp.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "$GITHUB_TOKEN" }

[roles.qa.mcp.browser]
type = "http"
url = "https://mcp.example.com/browser"
headers = { Authorization = "Bearer $BROWSER_MCP_TOKEN" }

Pi

A profile with agent = "pi" runs its sessions as pi. Pi has no MCP support of its own, so every pi session loads the third-party pi-mcp-adapter extension, which gives it the bees tools and the role’s MCP servers:

pi -p --mode json --no-extensions \
  -e npm:pi-mcp-adapter [-e <pi_packages entry>]... \
  --mcp-config <session>/pi-mcp.json --name bees-<session name> ...
[profiles.pi]
agent = "pi"
model = "anthropic/claude-sonnet-5"
effort = "high"

[roles.developer]
profile = "pi"
pi_packages = ["npm:@acme/pi-tools@1.2.3"]

Pi runs every tool without asking and has no sandbox of its own, and sbx has no template for it: it runs with sandbox = "none" or "container". In a container its home directory is a fresh tmpfs, so pi installs the adapter and the packages again at every session: the image needs pi, npm and access to the npm registry (and to the git hosts of git: packages), next to git and gh. Add pi to the image of The container mode:

RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

A container session is handed its provider key from the bees environment when one of these is set there: ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY or CEREBRAS_API_KEY. Another provider’s key goes in the role’s env.

Examples

Solo project, two developers

version = 4
# repo and default_branch are derived from the origin remote.

[filter]
label = "bees"

[scheduler]
max_developers = 2
qa_interval = "1h"

[global]
prompt = """
Use conventional commits. Never add a dependency without a comment saying why.
"""

[profiles.reviewer]
model = "sonnet"

[roles.developer]
commit_flags = "--signoff"

[roles.reviewer]
profile = "reviewer"
prompt = "Be strict about error handling and test coverage."
auto_merge = true
checks_timeout = "20m"

[roles.qa]
skills = ["https://github.com/anthropics/skills#skills/webapp-testing"]
timeout = "30m"

Team repository, only work assigned to me

version = 4

[project]
remote = "upstream"        # my origin is a fork; the team repository is upstream

[filter]
label = "kyle-bees"        # the kyle-bees:* labels are mine
require_label = false
assignee = "@me"

[scheduler]
product_manager_interval = "4h"

[global]
prompt_file = "docs/engineering-conventions.md"

[roles.product_manager]
enabled = false            # the team's own product manager owns the roadmap

[roles.developer]
prompt = "Only touch files under services/billing unless the issue says otherwise."

Requirements

bees run, tick, exec, status, issue create and issue link check the tools they drive before doing anything and refuse to start when one is missing or too old; bees init checks gh.

Tool Minimum Why
gh 2.50.0 gh pr checks --json (2.50.0) and gh api --slurp (2.49.0).
Claude Code (claude) 2.1.76 claude --name (2.1.76); --append-system-prompt-file, --effort, --plugin-dir, --strict-mcp-config and --fallback-model are older.

The Claude Code check only runs when at least one enabled role resolves to an agent profile whose agent is "claude", the default (see [profiles.<name>]). A factory where every enabled role resolves to "codex", "opencode" or "pi" never runs it, so claude does not need to be installed. Pi needs the pi-mcp-adapter package, which pi installs itself.

Set BEES_SKIP_VERSION_CHECK=1 to run with an unsupported version anyway.

Environment variables

Honoured by the bees command

Variable Effect
BEES_CONFIG Path of bees.toml when --config is not given. Set inside sessions.
BEES_CLAUDE_BIN The claude executable to run. Default claude on PATH.
BEES_CODEX_BIN The codex executable to run for a role whose agent is codex. Default codex on PATH.
BEES_OPENCODE_BIN The opencode executable to run for a role whose agent is opencode. Default opencode on PATH.
BEES_PI_BIN The pi executable to run for a role whose agent is pi. Default pi on PATH.
BEES_CACHE_DIR Cache directory for skill clones and generated plugins. Default ~/.cache/bees on Linux, ~/Library/Caches/bees on macOS.
BEES_SKIP_VERSION_CHECK When non-empty, skip the gh and claude version checks.
BEES_STATE_DIR bees mail and bees notes use this state directory without loading bees.toml, unless --config is given, in which case that file’s state directory wins. Set inside sessions.
BEES_SESSION_DIR Where bees done writes outcome.json; bees done refuses to run without it. Set inside sessions.
BEES_ROLE Default --from of bees mail send, and the role whose bees done statuses are validated. Set inside sessions.
BEES_ISSUE, BEES_PR Defaults for the --issue and --pr flags of bees mail send and bees done. Set inside sessions.
BEES_LOG_FORMAT, BEES_LOG_LEVEL Fallbacks for --log-format and --log-level. A flag beats them, and they beat [logging].

The variables marked set inside sessions are the only ones a session inherits. BEES_CLAUDE_BIN, BEES_CODEX_BIN, BEES_OPENCODE_BIN, BEES_PI_BIN, BEES_CACHE_DIR, BEES_SKIP_VERSION_CHECK, BEES_LOG_FORMAT and BEES_LOG_LEVEL configure the bees process you start and are not passed on, so a bees command a session runs itself sees their defaults. To give sessions one of them, put it in [global.env].

Exported into every session

A session inherits only the variables of the bees process environment its role is granted, never a BEES_* one:

Any other variable reaches a session only through its role’s env:

[global.env]
NPM_TOKEN = "$NPM_TOKEN"

On top of those, a session gets:

Variable Value
configured env Every [global.env] and [roles.<name>.env] entry, $VAR-expanded. Set first, so everything below wins over it.
BEES_ROLE The role name (developer, reviewer, …).
BEES_SESSION_DIR This session’s directory: prompts, transcript, outcome.json.
BEES_STATE_DIR The state directory.
BEES_CONFIG Path of bees.toml.
BEES_REPO owner/name.
BEES_LABEL filter.label.
BEES_ISSUE The issue the session works on, when any.
BEES_PR The pull request, when any.
BEES_BRANCH The checked-out branch, when any.
BEES_BIN Path of the bees executable. Its directory is also prepended to PATH, so a session can run bees mail and bees done. Not set in a container session, which has no bees binary.
PATH With a GitHub App and gh and git access, <state_dir>/github/bin first, holding the App’s gh, which runs yours with the App’s current token.
BEES_REVIEW_MODE checks in a reviewer session that diagnoses failed checks; unset otherwise.
SHELL The configured shell, when set.
GH_TOKEN github.token, when set, so the session’s gh acts as the factory. Empty with a GitHub App, whose gh fetches its own token.
the variable github.token names When github.token is a "$VAR" reference, that variable, holding the resolved token. The bees commands a session runs load bees.toml themselves, and a reference that expands to nothing is a load error, so the name has to survive the BEES_* strip. It is set in the environment only; nothing writes it into the session directory.
the variable notes.neo4j_api_key names The same, for a "$VAR" notes.neo4j_api_key, with notes.backend = "neo4j": the value the scheduler resolved, so the session’s own notes_read and notes_write can load [notes].
GIT_AUTHOR_NAME, GIT_COMMITTER_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_EMAIL github.git_name and github.git_email, when set.
GIT_CONFIG_COUNT, GIT_CONFIG_KEY_n, GIT_CONFIG_VALUE_n push.autoSetupRemote=true and push.default=current, so a plain git push works on a fresh branch without touching the clone’s git config; with github.token set, also an empty credential.helper followed by credential.helper=!gh auth git-credential, so an https push authenticates as the factory rather than through your stored credentials. With a GitHub App the second helper is <state_dir>/github/credential.sh, which answers with the App’s current token. Left alone when GIT_CONFIG_COUNT is already in the bees environment.

BEES_* variables are always set by bees for each session and never inherited, so a session started from inside another one, by a nested bees run or bees exec, never sees a stale issue, PR or branch. The BEES_* names bees puts back after the strip are the ones a "$VAR" github.token and a "$VAR" notes.neo4j_api_key read.