Configuration template

What fast_code_search_server --init config.toml writes: every key with its default and the comment that explains it. The narrative reference is API and configuration.

# Fast Code Search Configuration
# Generated template - customize as needed

[server]
# Address to bind the gRPC server to.
# Loopback by default: the server has no authentication and serves full file
# contents. Use "0.0.0.0:50051" only on a trusted network.
address = "127.0.0.1:50051"

# Start the gRPC API (default: true). Set false if you only use the web UI,
# REST API and fcs CLI. If the gRPC port is busy at startup the server logs
# an error and keeps running without gRPC rather than exiting.
enable_grpc = true

# Address to bind the HTTP/Web UI server to (same caveat as above)
web_address = "127.0.0.1:8080"

# Enable the web UI and REST API (default: true)
enable_web_ui = true

# Origins allowed to call the REST API from another site (CORS).
# Empty (default) = same-origin only, which is all the embedded UI needs.
# Example: ["http://localhost:3000"], or ["*"] to allow any origin
cors_origins = []

# Searches executing at once on the REST API; extra requests get 503 + Retry-After
max_concurrent_searches = 64

# Per-request timeout (seconds) for both servers
request_timeout_secs = 30

# Serve static UI files from a directory on disk instead of embedded assets.
# When set, the web server reads HTML/CSS/JS files from this path on every
# request so that UI edits are visible without recompiling the server.
# Useful during development. Unset (the default) = the assets embedded in the
# binary; TOML has no "unset" value, so this one key stays commented out.
# static_dir = "static"

# Web UI theme for people who haven't picked one: "bold", "corporate" or
# "corporate-dark". Each browser remembers its own choice.
default_theme = "bold"

# Ask people to pick a theme on their first visit. Set false on a shared
# server to use default_theme without asking (they can still change it from
# the palette button in the header).
theme_picker = true

[search]
# Search limits for every front end (web UI, REST, gRPC, fcs, MCP). The
# defaults were measured on a 372k-file corpus; see the "Limits" page of the
# book. Every limit that cuts a search is reported with the result.

# A search reads candidate files best first (by a per-file score that needs
# no reads) until it has collected enough matches to rank. This caps how
# many files it reads unless the request asks for more. 0 = no cap.
fast_rank_files = 0

# Most files a request may ask for (`max_files` on /api/search, the web UI's
# SEARCH MORE FILES). 0 = no limit; set one on a shared server.
max_fast_rank_files = 0

# Matches collected to rank a page. Every page ending before result 1000
# collects multiplier x 1000, between min and max; every page from there on
# collects max. One budget per range keeps offset pages consistent. A page
# is the best of what was collected, so a small budget gives a poor page 1
# for common words. Each match costs about 230 bytes while the search runs.
min_match_budget = 32768
match_budget_multiplier = 8
max_match_budget = 100000

# Most hits one file contributes to pages before result 1000 (its best, by
# score). 1000 leaves out nothing those pages could show.
per_file_matches = 1000

# Page size when a request gives none, and the largest it may ask for (the
# web UI's LOAD MORE and MCP follow max_page_size).
default_page_size = 50
max_page_size = 1000

# Deepest result offset a client may page to. Deep pages cost a scan of that
# many matches. 0 = no limit.
max_page_offset = 100000

# Most path matches (the FILES box) one request may ask for.
max_path_matches = 100

# Longest deadline a request may ask for, in seconds (request_timeout_secs
# still bounds every search).
max_timeout_secs = 30

# Most context lines around each hit.
max_context_lines = 10

[mcp]
# Hits search_code returns by default, and the most one call may ask for
# (at most search.max_page_size; agents page further with `offset`).
default_limit = 50
max_limit = 1000

# Files whose path matches the query, listed above search_code's hits.
file_matches = 20

# Most context lines search_code may ask for.
max_context_lines = 5

# read_file: lines returned by default, and the most one call returns.
read_file_lines = 200
max_read_file_lines = 1000

# Graph tools: files listed per level or group by default, and at most.
graph_default_limit = 50
graph_max_limit = 500

[indexer]
# Paths to index on startup
# Add your project directories here
paths = [
    # "C:/code/my-project",
    # "C:/code/another-project",
    # "/home/user/projects/my-app",
]

# Honour .gitignore / .ignore files under the indexed paths (default: true)
respect_gitignore = true

# File extensions to include (empty = all text files)
# Example: ["rs", "py", "js", "ts", "go", "c", "cpp", "h", "java"]
include_extensions = []

# Patterns to exclude from indexing
exclude_patterns = [
    "**/node_modules/**",
    "**/target/**",
    "**/.git/**",
    "**/build/**",
    "**/dist/**",
    "**/__pycache__/**",
    "**/venv/**",
    "**/.venv/**",
]

# Exact file paths to permanently exclude from indexing.
# Useful for files that cause crashes or are too large/noisy to be useful.
# After a crash, check fcs_last_processed.txt to identify the offending file.
# Example: ["/repo/src/generated/huge_file.rs"]
exclude_files = []

# Maximum file size to index in bytes (default: 10MB)
max_file_size = 10485760

# Enable encoding detection for non-UTF-8 text files (default: true)
# When enabled, files in Latin-1, Shift-JIS, UTF-16 etc. are transcoded to UTF-8.
# Disable for UTF-8-only codebases for slightly faster indexing.
transcode_non_utf8 = true

# Path to persistent index storage.
# The index is saved here and loaded on restart, so a restart takes seconds
# and only changed files are re-read. Remove the line to keep the index in
# memory only: it is then rebuilt from scratch on every start, and the server
# logs a warning saying so. Use one file per config. The directory is created
# on first save; `~` is expanded and relative paths resolve against this file.
index_path = "~/.local/share/fast_code_search/config.fcsidx"

# Save index after initial build completes (default: true)
# Only effective when index_path is set
save_after_build = true

# Save index after N file updates via watcher (default: 0 = disabled)
# When enabled, the index is periodically saved after this many watcher-triggered updates.
# Useful for long-running servers to persist incremental changes.
save_after_updates = 0

# Checkpoint every N files during the initial index build (default: 0 = disabled)
# If the process is killed mid-build, the next run resumes from the checkpoint.
# Recommended for very large repos: 20000. Has no effect if index_path is not set.
checkpoint_interval_files = 0

# Enable file watcher for incremental indexing (default: true)
# Changes to indexed files are detected and re-indexed automatically.
# Set to false to index once at startup (search then misses later edits
# until a restart; responses say how old the index is).
watch = true

# Enable tree-sitter symbol extraction (default: true)
# When enabled, function/class/struct definitions are parsed from source files
# and used to boost search relevance for symbol matches.
# Disable to reduce memory usage and indexing time at the cost of reduced relevance.
enable_symbols = true

# Start result paths with the indexed folder's name (default: true).
# Indexing /code/myapp shows myapp/src/main.rs; false shows src/main.rs.
# Only applies when a single path is indexed. Display only: file: filters
# and the saved index are unaffected.
show_root_name = true

# Files read and indexed per batch during the initial build (default: 500).
# Peak RAM scales with batch_size x average file size x ~4: lower it on small
# machines, raise it on large ones to reduce lock contention.
batch_size = 500

[telemetry]
# Enable OpenTelemetry trace export (default: false)
# Set to true to enable OTLP export (console logging is always active)
# Env overrides: OTEL_SDK_DISABLED=true, FCS_TRACING_ENABLED=true
enabled = false

# OTLP gRPC exporter endpoint (default: http://localhost:4317)
# Env override: OTEL_EXPORTER_OTLP_ENDPOINT
otlp_endpoint = "http://localhost:4317"

# Service name reported to the collector
# Env override: OTEL_SERVICE_NAME
service_name = "fast_code_search"