Skip to main content
brv ships with operational defaults that suit most users. The brv settings command group lets you inspect those defaults and override them when you need more (or less) headroom. Changes apply after brv restart. The daemon reads settings.json once at startup so every agent it spawns runs against the same configuration for the lifetime of the process.

​
Subcommands

brv settings                       # List all settings, grouped by category
brv settings list                  # Alias for the bare `brv settings`
brv settings get <key>             # Show current value, default, and range
brv settings set <key> <value>     # Update one key (restart required)
brv settings reset <key>           # Restore one key to its default (restart required)
Every subcommand accepts --format json for scripting. Validation errors (unknown key, value out of range, wrong unit) exit with code 1 and a message naming the offending key.

​
Available keys

Most settings require brv restart to take effect — the Restart column flags the exceptions. Keys in the Updates category take effect on the next brv invocation, no restart needed.

​
Concurrency

KeyDefaultRangeRestartWhat it controls
agentPool.maxSize101–100RequiredHow many projects can be active at the same time. One agent process per project.
agentPool.maxConcurrentTasksPerProject51–50RequiredMax parallel brv curate / brv query tasks within a single project.

​
LLM

KeyDefaultRangeRestartWhat it controls
llm.iterationBudgetMs600000 (10 min)60000–3600000 (1 min – 1 hour)RequiredWall-clock budget for one agentic loop on a single task.
llm.requestTimeoutMs120000 (2 min)10000–3600000 (10 s – 1 hour)RequiredWall-clock budget for one direct LLM HTTP request. Must satisfy llm.requestTimeoutMs <= llm.iterationBudgetMs.

​
Task history

KeyDefaultRangeRestartWhat it controls
taskHistory.maxEntries100010–10000RequiredPer-project cap on the task records the Tasks tab and brv query-log view retain. Older entries roll off automatically.

​
Updates

KeyDefaultValuesRestartWhat it controls
update.checkForUpdatestruetrue / falseNot requiredWhether brv checks for new versions at startup and runs the background auto-update. Set to false to silence the y/n update prompt and stop background auto-update; manual brv update still works.

​
Value formats

brv settings set parses the value differently depending on the key’s unit:
  • Count keys (e.g. agentPool.maxSize, taskHistory.maxEntries) — plain integer. 
    brv settings set agentPool.maxSize 25
  • Duration keys (llm.iterationBudgetMs, llm.requestTimeoutMs) — duration string or raw milliseconds. Accepted suffixes are ms, s, m, h; multi-part durations are written with the largest unit first. Whitespace between parts is optional. Fractional values (1.5h) are rejected. 
    brv settings set llm.iterationBudgetMs 30m       # 30 minutes
brv settings set llm.iterationBudgetMs "1h 30m"  # 90 minutes
brv settings set llm.iterationBudgetMs 1800000   # raw ms

​
Where settings live

Settings persist in settings.json under the global ByteRover data directory:
OSPath
Linux$XDG_DATA_HOME/brv/settings.json (defaults to ~/.local/share/brv/settings.json)
macOS~/Library/Application Support/brv/settings.json
Windows%LOCALAPPDATA%/brv/settings.json
Set the BRV_DATA_DIR environment variable to override the directory. The file is rewritten atomically (temp + rename) on every brv settings set / reset, so a crash mid-write cannot leave a half-written file. If the daemon encounters a malformed settings.json at startup, it logs one warning per problem and falls back to the registered defaults — the bad file is left in place for you to inspect or repair.

​
When to change a setting

Most users never need to touch these. The cases worth changing them for:
  • Raise llm.iterationBudgetMs when a single brv curate or brv query on a slow local LLM (Ollama on CPU, heavy quantization, cold model load) routinely hits the default 10-minute cap on legitimate work. Lower it on cloud providers when you want a stuck task to surface as an error faster.
  • Tune llm.requestTimeoutMs in lockstep with the iteration budget when you change profile. Suggested presets:
    Profilellm.requestTimeoutMsllm.iterationBudgetMs
    Cloud120000 (2 min)600000 (10 min)
    Local LLM, fast GPU300000 (5 min)1200000 (20 min)
    Local LLM, CPU / heavy quantization900000 (15 min)3600000 (60 min)
    The constraint llm.requestTimeoutMs <= llm.iterationBudgetMs is enforced both on set and at daemon startup; a file that violates it falls back to defaults for both keys.
  • Raise agentPool.maxSize if you actively switch between more than 10 projects in a single daemon session and want them all to keep warm.
  • Lower taskHistory.maxEntries if disk usage from the per-project task journals starts mattering, or raise it if you want deeper history for audit.
  • Set update.checkForUpdates to false if you manage brv versions on your own schedule (pinned in CI, controlled rollouts, air-gapped environments) and don’t want the y/n update prompt at startup. Unlike the other keys, this one takes effect on the next brv invocation — no restart needed. See also Installation & Updates FAQ.

​
--timeout migration

Earlier versions of brv curate, brv query, and brv dream accepted a --timeout flag. The flag is still accepted for back-compat but now prints --timeout is deprecated and has no effect. to stderr and is ignored. Use llm.iterationBudgetMs instead: 
brv settings set llm.iterationBudgetMs 30m
brv restart

​
Example session

$ brv settings
Settings - scope: global
Run `brv restart` to apply changes.

CONCURRENCY
  agentPool.maxSize                         10       (default 10)         1-100
  agentPool.maxConcurrentTasksPerProject    5        (default 5)          1-50

LLM
  llm.iterationBudgetMs                     10m      (default 10m)        1m-1h
  llm.requestTimeoutMs                      2m       (default 2m)         10s-1h, max loop budget

TASK HISTORY
  taskHistory.maxEntries                    1,000    (default 1,000)      10-10,000

UPDATES
  update.checkForUpdates                    true     (default true)

Set:   brv settings set <key> <value>
Reset: brv settings reset <key>

$ brv settings set agentPool.maxSize 25
Setting saved: agentPool.maxSize = 25. Run `brv restart` to apply.

$ brv settings set update.checkForUpdates false
Setting saved: update.checkForUpdates = false.

$ brv settings get agentPool.maxSize --format json
{"command":"settings get","success":true,"data":{"key":"agentPool.maxSize","current":25,"default":10,"min":1,"max":100,"unit":"count","category":"concurrency","restartRequired":true}}

​
Next steps

CLI Reference

Full command-by-command reference for brv.

Daemon-First Architecture

Why agentPool.* settings exist and how the pool reuses processes.

Tasks tab

What taskHistory.maxEntries retains and how it surfaces in the WebUI.

Local Web UI Configuration

Browse and edit the same settings from brv webui.