Configuration

Every public setting for scorchd, the scorch client, browser policy, metasearch credentials, limits, and structured logging.

Precedence

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

A command-line flag such as --max-concurrency 8
The corresponding environment variable such as SCORCH_MAX_CONCURRENCY=8
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

Variable	Default	Values / meaning	CLI flag
`SCORCH_BIND`	`127.0.0.1:33000`	Socket address for the HTTP API.	`--bind`
`SCORCH_BROWSER`	`obscura`	Default renderer: `obscura` or `chromium`.	`--browser`
`SCORCH_ALLOWED_BROWSERS`	`obscura`	Comma-separated request allowlist.	`--allowed-browsers`
`SCORCH_BROWSER_PATH`	`chromium`	Chromium executable path or command name. Used only by Chromium.	`--browser-path`
`SCORCH_OBSCURA_STEALTH`	`true`	`true` for Chrome-like transport identity; `false` for faster standard transport.	`--obscura-stealth`
`SCORCH_MAX_CONCURRENCY`	`4`	Global concurrent operation ceiling. Crawl concurrency cannot exceed it.	`--max-concurrency`
`SCORCH_MAX_RESPONSE_BYTES`	`5242880`	Maximum bytes accepted from one remote response; default 5 MiB.	`--max-response-bytes`
`SCORCH_JOB_TTL_SECS`	`900`	Retention after crawl completion; default 15 minutes.	`--job-ttl-secs`
`SCORCH_SEARCH_ENGINES`	`bing,duckduckgo,naver,wikipedia`	Comma-separated server allowlist for internal search engines.	`--search-engines`
`SCORCH_BRAVE_SEARCH_API_KEY`	unset	Required when `brave` is enabled.	`--brave-search-api-key`
`SCORCH_GOOGLE_SEARCH_API_KEY`	unset	Google Custom Search JSON API key.	`--google-search-api-key`
`SCORCH_GOOGLE_SEARCH_ENGINE_ID`	unset	Google Programmable Search Engine ID; required with the Google key.	`--google-search-engine-id`
`RUST_LOG`	service default	Tracing filter, for example `scorch=debug` or `scorch=info,tower_http=debug`.	—
`SCORCH_LOG_FORMAT`	compact	Set to `json` for newline-delimited JSON logs.	—

Client environment variables

Variable	Default	Used by
`SCORCH_API_URL`	`http://127.0.0.1:33000`	Every `scorch` web command, benchmark, and the MCP adapter.

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.

Browser policy

Browser configuration has two independent parts:

SCORCH_BROWSER chooses the backend used when a request omits options.browser.
SCORCH_ALLOWED_BROWSERS defines every backend a request is permitted to select.

The default is intentionally narrow:

SCORCH_BROWSER=obscura
SCORCH_ALLOWED_BROWSERS=obscura
SCORCH_OBSCURA_STEALTH=true
scorchd

Enable Chromium as a request-selectable compatibility backend:

SCORCH_ALLOWED_BROWSERS=obscura,chromium \
SCORCH_BROWSER_PATH=/usr/bin/chromium \
scorchd

Make Chromium the only backend:

SCORCH_BROWSER=chromium \
SCORCH_ALLOWED_BROWSERS=chromium \
SCORCH_BROWSER_PATH=/usr/bin/chromium \
scorchd

If a request names a backend outside the allowlist, Scorch returns HTTP 400 rather than silently switching it. The configured default should therefore also appear in the allowlist.

Stealth versus throughput: leave Obscura stealth enabled for Chrome-like network behavior. Set SCORCH_OBSCURA_STEALTH=false only where the standard transport's higher throughput is preferable.

Search engine policy

The allowed values are bing, brave, duckduckgo, google, naver, and wikipedia. Search requests never carry this list.

Credential-free default

SCORCH_SEARCH_ENGINES=bing,duckduckgo,naver,wikipedia scorchd

Add Brave

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

Add Google Custom Search

SCORCH_SEARCH_ENGINES=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.

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.

Throughput-oriented Obscura

SCORCH_BROWSER=obscura \
SCORCH_ALLOWED_BROWSERS=obscura \
SCORCH_OBSCURA_STEALTH=false \
SCORCH_MAX_CONCURRENCY=8 \
scorchd

Do not bind publicly without a gateway. SCORCH_BIND=0.0.0.0:33000 exposes an unauthenticated web-fetching API. Scorch's SSRF policy does not replace caller authentication.