> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> How ByteRover CLI uses a background daemon for instant startup, agent pool reuse, and shared state
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, MCP server, or the local web UI — 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 │
│ HTTP Server (serves the local web UI) │
│ Agent Pool (forked LLM worker processes) │
│ Task Router │
│ State Server (config, auth, providers) │
└──────┬──────────┬──────────────┬────────────────┬───────┘
│ │ │ │
TUI Client CLI Commands MCP Server Web UI
(optional) brv query brv mcp brv webui
brv curate (coding agents)
brv status
```
The TUI, CLI commands, MCP server, and web UI are all equal clients. None of them own the runtime — the daemon does.
## Before vs After
| | Before (v1.x) | After (v2.0) |
| ------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
| **Runtime** | LLM loop and task execution lived inside the TUI process | Daemon is a standalone background process |
| **TUI requirement** | Agents needed `brv` (the TUI) running to function | TUI is optional — agents connect directly to the daemon |
| **Startup** | Had to manually start the TUI first | Any `brv` command auto-starts the daemon on demand |
| **State sharing** | Tied to the TUI session | Shared across all clients via the daemon's state server |
| **Agent processes** | Created and destroyed per session | Pooled 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:
```bash theme={null}
# 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.
| Platform | Metadata 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.
By default, the pool supports up to 10 project agents, each handling up to 5 tasks simultaneously. Both numbers are tunable via [`brv settings`](/reference/brv-settings) (`agentPool.maxSize` and `agentPool.maxConcurrentTasksPerProject`).
### 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:
```bash theme={null}
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](/headless-mode/overview) documentation.
## Technical Details
Key constants from the daemon runtime:
| Parameter | Value |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| Transport | Socket.IO (WebSocket-only) |
| Port range | 49152–65535 (dynamic) |
| Heartbeat interval | 5 seconds |
| Server idle timeout | 30 minutes |
| Agent idle timeout | 15 minutes |
| Max agent pool size | 10 processes (default; tunable via [`agentPool.maxSize`](/reference/brv-settings)) |
| Max concurrent tasks per agent | 5 (default; tunable via [`agentPool.maxConcurrentTasksPerProject`](/reference/brv-settings)) |
## Next Steps
Browser-based client served by the daemon
Non-interactive execution for CI/CD pipelines and automation
Complete command reference for all ByteRover CLI commands
Connect coding agents like Cursor, Claude Code, and Windsurf
Connect external LLM providers and bring your own API key