Configuration

Precedence

Most scorchd settings have three layers. The first defined value wins:

1. A command-line flag such as --max-concurrency 8
2. The corresponding environment variable such as SCORCH_MAX_CONCURRENCY=8
3. The compiled default

Use scorchd --help to inspect the active binary. Logging variables are environment-only. The lightweight client has its own endpoint setting and does not read server runtime configuration.

Server environment variables

Client environment variables

The global --api-url option overrides this variable for one invocation:

scorch --api-url https://scorch.internal.example search "browser automation"

The client does not inspect SCORCH_BIND. The bind address describes the server's listening socket; the API URL describes how a client reaches it through local networking or a gateway.

Obscura renderer

Every page scrape uses embedded Obscura with its Chrome-like stealth transport statically enabled. There is no direct scrape transport, backend selector, browser executable path, request-level rendering mode, or daemon stealth override. Stealth changes browser, HTTP, and TLS fingerprints; it does not rotate the egress IP or solve authorization, rate-limit, geography, or active-challenge failures.

Search engine policy

The credential-free values are bing, brave-web, crates-io, crossref, docker-hub, duckduckgo, github, google-cse, hacker-news, hugging-face, mwmbl, npm, nvd, openalex, open-library, pubmed, wikidata, wikipedia, and yahoo. The optional credential-backed values are brave and google. The server allowlist is an upper bound.

Credential-free policy

SCORCH_SEARCH_ENGINES=bing,brave-web,crates-io,crossref,docker-hub,duckduckgo,github,google-cse,hacker-news,hugging-face,mwmbl,npm,nvd,openalex,open-library,pubmed,wikidata,wikipedia,yahoo scorchd

Requests that omit engines use only DuckDuckGo when the server allows it. Other general, package, developer, security, and research sources are request-explicit. Brave Web, Google CSE, and Yahoo depend on public frontend protocols and remain best-effort. If DuckDuckGo is not allowed, requests must select an allowed engine explicitly.

Add the official Brave API

SCORCH_SEARCH_ENGINES=bing,brave,duckduckgo,wikipedia \
SCORCH_BRAVE_SEARCH_API_KEY='...' \
scorchd

Add the credentialed Google JSON API

SCORCH_SEARCH_ENGINES=bing,duckduckgo,google,wikipedia \
SCORCH_GOOGLE_SEARCH_API_KEY='...' \
SCORCH_GOOGLE_SEARCH_ENGINE_ID='...' \
scorchd

Missing credentials for an enabled credentialed engine are startup configuration errors. Secrets are redacted from Scorch's diagnostics. Google documents that Custom Search JSON API is unavailable to new customers and will be discontinued on January 1, 2027, so the adapter is useful only for existing customers during migration.

Logging

Operational logs are written to stderr. CLI result JSON and MCP JSON-RPC framing stay on stdout, so they can be piped without log contamination.

# Human-readable debug output
RUST_LOG=scorch=debug scorchd

# Production-friendly newline-delimited JSON
SCORCH_LOG_FORMAT=json RUST_LOG=scorch=info scorchd

Info-level logs include startup and shutdown, request IDs, method, status and latency, operation outcomes, browser lifecycle, engine selection, and crawl lifecycle. Request bodies, search text, credentials, and URL query strings are not logged at info level.

Deployment recipes

Local development

RUST_LOG=scorch=debug scorchd

Private service behind a gateway

SCORCH_BIND=127.0.0.1:33000 \
SCORCH_MAX_CONCURRENCY=8 \
SCORCH_LOG_FORMAT=json \
RUST_LOG=scorch=info \
scorchd

Terminate TLS and enforce authentication, request size, rate, and network policy at the gateway. Preserve or generate request IDs for log correlation.

Higher browser concurrency

SCORCH_MAX_CONCURRENCY=8 scorchd