Configuration
benchbar has no settings file of its own to edit. A bench is configured by the flags you pass once (they are remembered per bench), the profile and bundle it was installed with, and a few environment variables.
Profiles
Profiles pick the Frappe branch and the matching toolchain:
| Profile | Frappe | ERPNext | Python | Node | MariaDB |
|---|---|---|---|---|---|
v15-lts (default) | version-15 | version-15 | python@3.11 | node@22 | mariadb@10.11 |
v16-lts | version-16 | version-16 | python@3.14 | node@24 | mariadb@11.8 |
Every profile also installs pkgconf (pkg-config) and
mariadb-connector-c, which mysqlclient needs to build on v16. When
uv is on PATH, bench itself is installed with uv tool install frappe-bench, as the Frappe docs now recommend; an existing pipx install
is kept, and doctor says which one owns bench.
Each profile accepts a range of MariaDB servers: 10.6 to 10.11 for
v15-lts, 10.6 to 11.8 for v16-lts. A v16 bench shares the
mariadb@10.11 server a v15 bench runs, so one MariaDB serves every
bench. The profiles are defined in config/release-profiles.tsv.
--profile NAME picks one for install; a bench remembers its profile.
A name that is not built in is looked up as a
team profile.
App bundles
App bundles pick what install adds beyond Frappe: minimal
(erpnext), common (erpnext hrms payments), extended (erpnext hrms payments crm helpdesk insights). Definitions live in config/:
config/app-bundles.tsv for the bundles, config/apps.tsv for the app
registry that benchbar app add NAME reads, with the branch each app
follows per profile.
benchbar install --profile v16-lts --bundle commonMARIADB_ROOT_PASSWORD='...' ADMIN_PASSWORD='...' benchbar install --yes # non interactivebenchbar autostart off # never start at login--yes accepts every default and confirmation, including the sudo line
for /etc/hosts; the sudo password prompt itself still appears.
ADMIN_PASSWORD must be in the environment. MARIADB_ROOT_PASSWORD is
needed only when MariaDB already has a root password that the Keychain
does not know: a fresh MariaDB gets a generated one.
Team profile files
A team profile is NAME.toml in ~/.config/benchbar/profiles/ (your
own files and the ones profile import wrote), then in each
subscription (~/.config/benchbar/sources/, in the order of
~/.config/benchbar/sources.list), then in each folder of
BENCHBAR_PROFILE_PATH. The first file of a name wins, and a built in
profile of the same name wins over all of them. The format is a strict
subset of TOML: strings, booleans, integers and one line lists; no
escapes, no inline tables.
| Key | Required | What it sets |
|---|---|---|
schema | no | 1 or 2; 1 when absent. A file with any schema 2 key must say schema = 2 |
base | yes | The built in profile for Python, Node and MariaDB, for example "v15-lts" |
description | no | One line shown by profile list |
frappe_branch | no | Another Frappe branch than the base’s |
frappe_commit | no | A commit to pin frappe to (7 to 40 lower case hex characters). install checks that the clone has it before it builds, and stops otherwise |
erpnext_commit | no | The same for erpnext (also [[apps]] commit for an erpnext listed there) |
bundle | no | An app bundle, instead of [[apps]]: a file with both is refused |
site | no | The default site name for install |
scheduler | no | true to run the scheduler |
source | no, schema 2 | Where profile import fetched the file (an https URL or a path); profile update fetches it again |
exported_from | no, schema 2 | Written by profile export, for example "benchbar 0.6.0, 2026-09-29" |
[[apps]] name | yes, per app | The app’s folder name |
[[apps]] repo | yes, per app | Its git URL. A URL with a user name or token is refused |
[[apps]] branch | yes, per app | The branch to clone |
[[apps]] commit | no | A commit to pin; a clone that does not reach it stops install before anything is built |
[[apps]] access | no, schema 2 | public, private, personal or unknown: who can read the repo, as profile export found it |
[[apps]] requires | no, schema 2 | The apps this one needs, for example ["acme_base"]. install --profile leaves an app out when one it requires cannot be read |
A benchbar before 0.6 refuses a schema 2 file with “not supported:
schema 2”, so update benchbar before you share one. An example is in
Teams. benchbar profile create
writes one from a bench you have, benchbar profile export a copy to
share (Sharing a profile).
Passwords
| What | Where it lives | When you need it |
|---|---|---|
| MariaDB root | your Keychain, item benchbar-mariadb (on Linux a 0600 file in the state folder); benchbar mariadb-password prints it after a confirmation | rarely: another bench new-site, or mariadb -u root -p |
| Administrator | you choose it during benchbar install or site add, or ADMIN_PASSWORD | every login at http://<site>:<port>, by default http://macdev:8000 |
Environment variables
| Variable | Used by | What it does |
|---|---|---|
MARIADB_ROOT_PASSWORD | install, site add, pull | The MariaDB root password. A fresh MariaDB gets a generated one when unset; an existing one is read from the Keychain |
ADMIN_PASSWORD | install, site add, pull | The Administrator password of a new site; for pull, a new Administrator password for the copy |
BENCHBAR_PROFILE_PATH | --profile, profile | Colon separated folders with team profiles, for example a clone of your team’s config repo |
BENCHBAR_OFFLINE | install, profile, doctor | BENCHBAR_OFFLINE=1: no network for team profiles, and no remote branch checks in install; reachability is null and doctor does not fetch subscriptions |
BENCHBAR_LOCK | lock, doctor | The lockfile path, when --lock is not given |
BENCH_DIR | every command | The bench to act on when --bench-dir is not given; checked before the remembered bench |
SITE_NAME | every command | The site to act on when --site is not given; checked before the remembered site |
OFFLINE | install, doctor, app focus, profile | OFFLINE=1: no network for version checks, --fetch and team profiles (like BENCHBAR_OFFLINE=1) |
BENCHBAR_REPORT_DIR | report | Where the zip goes instead of ~/Desktop |
NO_COLOR | every command | NO_COLOR=1 turns off colors and spinners, like --plain |
BENCHBAR_NO_HANDOFF | every command | BENCHBAR_NO_HANDOFF=1: Homebrew’s or the one line installer’s benchbar runs itself instead of handing off to the CLI inside BenchBar.app (0.7.1) |
BENCHBAR_NONINTERACTIVE | every command | BENCHBAR_NONINTERACTIVE=1: nothing is asked. A command that lacks an input names all of them in one error before it takes the lock. --for-agent and benchbar mcp set it |
BENCHBAR_SUDO | install, adopt, repair, ports apply, site hosts | BENCHBAR_SUDO=gui (macOS): each root step asks in macOS’s own password dialog, at most two per run. The BenchBar app sets it |
The one line installer reads BENCHBAR_HOME (the checkout, default
~/.local/share/benchbar), BENCHBAR_BIN_DIR (default ~/.local/bin),
BENCHBAR_APP_DIR (default ~/Applications) and BENCHBAR_RC_FILE
(default ~/.zshrc). The CLI writes its helper block to $ZDOTDIR/.zshrc
when ZDOTDIR is set, and remembers that file, so a run started by the
app or launchd (without the terminal’s variables) finds the same block.
Bench discovery
Point the tool at any bench once with --bench-dir; the path is
remembered. Without it, benchbar uses BENCH_DIR when it is set, then
the remembered bench, then ~/frappe-bench, ~/dev/frappe-bench, and
any folder directly under ~ or ~/dev (one level deep) that holds
sites/common_site_config.json. benchbar scan PATH looks deeper.
The first bench you install or adopt becomes the default; a second one
keeps the first as the default unless you pass --make-default. See
Several benches.
Port blocks
Each bench uses a block of four ports: web 8000 + n, socketio
9000 + n, Redis 11000 + n and 13000 + n. --port-offset N picks
block N for install, adopt or service. How a clashing bench is
moved is in Port blocks.
Where state lives
- benchbar’s state folder is
~/.local/state/benchbarfor Homebrew, the one line installer and the CLI inside BenchBar.app, and.benchbarnext to the CLI in a git checkout.benchbar whereshows it. - Per bench settings (profile, site, scheduler, autostart, lockfile
path) live in its
benches/folder, one file per bench. - The logs and backups of every mutating run are in the same folder:
logs/<timestamp>.logandbackups/<timestamp>/. - The runner writes
<bench>/logs/.benchbar/state.jsonon every state change (schema). - Everything else benchbar writes is listed in Troubleshooting.