Skip to main content
ByteRover CLI v2.0.0 introduces a daemon-first architecture. The core runtime is now a background daemon process that any client — TUI, CLI commands — can connect to independently. The interactive TUI is no longer required for agents to work; it’s just another client.
Daemon-first architecture requires ByteRover CLI v2.0.0 or later.

​
Architecture

The daemon (brv-server) runs as a standalone background process. All clients connect to it over Socket.IO: 
┌─────────────────────────────────────────────┐
│           Daemon (brv-server)               │
│                                             │
│  Socket.IO Transport Server                 │
│  Agent Pool (forked LLM worker processes)   │
│  Task Router                                │
│  State Server (config, auth, providers)     │
└──────┬──────────┬──────────────┬────────────┘
       │          │              │
   TUI Client  CLI Commands  MCP Server
   (optional)  brv query     brv mcp
               brv curate    (coding agents)
               brv status
The TUI, CLI commands, and MCP server are all equal clients. None of them own the runtime — the daemon does.

​
Before vs After

Before (v1.x)After (v2.0)
RuntimeLLM loop and task execution lived inside the TUI processDaemon is a standalone background process
TUI requirementAgents needed brv (the TUI) running to functionTUI is optional — agents connect directly to the daemon
StartupHad to manually start the TUI firstAny brv command auto-starts the daemon on demand
State sharingTied to the TUI sessionShared across all clients via the daemon’s state server
Agent processesCreated and destroyed per sessionPooled and reused across commands (no cold starts)

​
Auto-Start on Demand

Every CLI command auto-spawns the daemon if it’s not already running. No manual setup needed: 
# Daemon starts automatically — no need to run `brv` first
brv query "how does auth work?"
# spawns daemon → connects → executes → returns

brv curate "JWT tokens expire in 24h" --files src/auth.ts
# same flow — reuses the already-running daemon

brv status
# same flow
You never need to manage the daemon manually. It starts when you need it and shuts down when you don’t.

​
Daemon Lifecycle

​
Spawns on first use

Any brv command auto-starts the daemon if it’s not already running. The daemon spawns as a detached child process, selects a random port from the dynamic range (49152–65535), and writes its metadata to a platform-specific data directory so clients can find it.
PlatformMetadata path
macOS~/Library/Application Support/brv/daemon.json
Linux$XDG_DATA_HOME/brv/daemon.json (defaults to ~/.local/share/brv/daemon.json)
Windows%LOCALAPPDATA%/brv/daemon.json

​
Stays alive

The daemon persists across commands. Subsequent calls reuse the same process — no startup overhead after the first command.

​
Agent pool reuse

Each project gets a dedicated LLM worker process, forked on demand when the first task arrives. Once forked, the agent stays warm and is reused for subsequent tasks on the same project — eliminating cold starts on back-to-back commands. The pool supports up to 10 project agents, each handling up to 5 tasks simultaneously.

​
Hot-swap providers

Switching LLM providers via /providers or brv providers connect propagates instantly to all running agents through the daemon’s event system. No restart required.

​
Auto-shutdown

The daemon shuts down automatically after 30 minutes of inactivity. Individual agent processes are cleaned up after 15 minutes of being idle. This keeps your system clean without any manual intervention.

​
Singleton lock

A global instance lock prevents multiple daemons from running simultaneously. The lock uses an atomic temp-file-and-rename mechanism to avoid race conditions when multiple commands start at the same time.

​
Headless & CI/CD

All CLI commands support --format json for structured output, making ByteRover fully scriptable: 
brv query "what are the API endpoints?" --format json
brv curate "Added rate limiting to /api/v2" --files src/middleware.ts --format json
brv status --format json
The daemon auto-starts in headless environments just as it does interactively — no extra configuration needed. For full details on headless execution, JSON output format, authentication for automation, and CI/CD integration, see the Headless Mode documentation.

​
Technical Details

Key constants from the daemon runtime:
ParameterValue
TransportSocket.IO (WebSocket-only)
Port range49152–65535 (dynamic)
Heartbeat interval5 seconds
Server idle timeout30 minutes
Agent idle timeout15 minutes
Max agent pool size10 processes
Max concurrent tasks per agent5

​
Next Steps

Headless Mode

Non-interactive execution for CI/CD pipelines and automation

CLI Reference

Complete command reference for all ByteRover CLI commands

Agent Connectors

Connect coding agents like Cursor, Claude Code, and Windsurf

LLM Providers

Connect external LLM providers and bring your own API key