Settings reference

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

Key	Default	Range	Restart	What it controls
`agentPool.maxSize`	`10`	`1`–`100`	Required	How many projects can be active at the same time. One agent process per project.
`agentPool.maxConcurrentTasksPerProject`	`5`	`1`–`50`	Required	Max parallel `brv curate` / `brv query` tasks within a single project.

LLM

Key	Default	Range	Restart	What it controls
`llm.iterationBudgetMs`	`600000` (10 min)	`60000`–`3600000` (1 min – 1 hour)	Required	Wall-clock budget for one agentic loop on a single task.
`llm.requestTimeoutMs`	`120000` (2 min)	`10000`–`3600000` (10 s – 1 hour)	Required	Wall-clock budget for one direct LLM HTTP request. Must satisfy `llm.requestTimeoutMs <= llm.iterationBudgetMs`.

Task history

Key	Default	Range	Restart	What it controls
`taskHistory.maxEntries`	`1000`	`10`–`10000`	Required	Per-project cap on the task records the Tasks tab and `brv query-log view` retain. Older entries roll off automatically.

Updates

Key	Default	Values	Restart	What it controls
`update.checkForUpdates`	`true`	`true` / `false`	Not required	Whether `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:

OS	Path
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:
Profile llm.requestTimeoutMs llm.iterationBudgetMs
Cloud 120000 (2 min) 600000 (10 min)
Local LLM, fast GPU 300000 (5 min) 1200000 (20 min)
Local LLM, CPU / heavy quantization 900000 (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.

Profile	`llm.requestTimeoutMs`	`llm.iterationBudgetMs`
Cloud	`120000` (2 min)	`600000` (10 min)
Local LLM, fast GPU	`300000` (5 min)	`1200000` (20 min)
Local LLM, CPU / heavy quantization	`900000` (15 min)	`3600000` (60 min)

`--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.

Getting Started

LLM Providers

Agent Connectors

Context Tree

Knowledge Sharing

Memory Swarm

Git-Semantic Version Control

Review Changes

BRV Hub

Headless Mode

Daemon-First Architecture

Local Web UI

Reference

FAQs

Security

ByteRover Cookbook

Settings reference

Subcommands

Available keys

Concurrency

LLM

Task history

Updates

Value formats

Where settings live

When to change a setting

`--timeout` migration

Example session

Next steps

CLI Reference

Daemon-First Architecture

Tasks tab

Local Web UI Configuration

​Subcommands

​Available keys

​Concurrency

​LLM

​Task history

​Updates

​Value formats

​Where settings live

​When to change a setting

​--timeout migration

​Example session

​Next steps

CLI Reference

Daemon-First Architecture

Tasks tab

Local Web UI Configuration

Subcommands

Available keys

Concurrency

LLM

Task history

Updates

Value formats

Where settings live

When to change a setting

`--timeout` migration

Example session

Next steps