Environment variables

blop reads environment variables for the monitoring collector, OpenTelemetry, active-runner provider configuration, optional platform upload, and debugging. Monitoring settings currently resolve in this order: CLI flag, environment variable, built-in default. Project and user configuration layers are planned but are not loaded by the monitor yet.

Monitor (collector and queries)

These control the local collector and the CLI queries that talk to it. blop status --json reports the effective non-secret configuration.

Variable	Used for
BLOP_MONITOR_HOST	Bind host for blop monitor start and query base URL (default 127.0.0.1)
BLOP_MONITOR_PORT	Bind port (default 27686)
BLOP_MONITOR_URL	Explicit base URL for query commands; never silently falls back to a discovered instance
BLOP_MONITOR_DB_PATH	SQLite database path (default: platform state directory, e.g. ~/.local/state/blop/monitor/telemetry.sqlite)
BLOP_MONITOR_STATE_DIR	Override the state directory the default database lives in
BLOP_MONITOR_RETENTION_HOURS	Retention window in hours (default 168, one week)
BLOP_MONITOR_MAX_DB_SIZE_MB	Approximate maximum database size before bounded oldest-first eviction (default 1024)
BLOP_MONITOR_RETENTION_TRACE_BATCH	Maximum traces removed in one size-retention batch (default 100)
BLOP_MONITOR_RETENTION_LOG_BATCH	Maximum logs removed in one size-retention batch (default 5000)
BLOP_MONITOR_RETENTION_INTERVAL_SECONDS	How often retention trims the store (default 10)
BLOP_MONITOR_TRACE_LOOKBACK_MINUTES	Collector-side default lookback for trace queries (default 1440)
BLOP_MONITOR_TRACE_LIMIT	Collector-side default trace fetch limit (default 100)
BLOP_MONITOR_LOG_LIMIT	Collector-side default log fetch limit (default 100)

CLI queries pass a 15-minute lookback by default; collector-side defaults apply when the CLI does not send one. List results are hard-capped (100 traces, 500 spans or logs, 24-hour lookback).

When no URL, host, or port is explicit, the CLI discovers registered local collectors. It chooses the longest working-directory match, accepts a sole running instance, and rejects ambiguity. Explicit settings always win and are never replaced after a connection failure.

OpenCode integration

These variables override discovery for blop setup opencode and the blop opencode launcher. Most users do not need to set them.

Variable	Used for
BLOP_OPENCODE_BIN	Absolute path to the OpenCode executable.
BLOP_OPENCODE_SETUP_PATH	Setup record path; defaults to the XDG config directory.
OPENCODE_CONFIG	OpenCode config file to update; relative paths resolve from the current directory.
XDG_CONFIG_HOME	Base directory for default OpenCode and Blop integration config paths.

The launcher sets OTEL_EXPORTER_OTLP_ENDPOINT on the OpenCode child process to the collector selected during setup. It preserves existing OTEL_RESOURCE_ATTRIBUTES and adds service.namespace=opencode-agents only when no namespace is present.

OpenTelemetry

Two roles, one standard. Your application uses the standard OTLP/HTTP exporter variables to send telemetry to the blop collector; the active browser runner uses the same variables to export its own telemetry from blop to any OTLP backend.

Point any OpenTelemetry SDK at the local collector:

$ OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:27686 pnpm test

Variable	Used for
OTEL_EXPORTER_OTLP_ENDPOINT	Collector base URL; the signal path is appended
OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT	Full URL for one signal, used verbatim; wins over the generic one
OTEL_EXPORTER_OTLP_HEADERS	Comma-separated key=value headers, e.g. auth
OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_HEADERS	Same, applied to one signal
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf (default) or http/json
OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_PROTOCOL	Protocol override for one signal
OTEL_EXPORTER_OTLP_TIMEOUT	Export timeout in milliseconds, capped at 4.5 seconds
OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_TIMEOUT	Timeout override for one signal
OTEL_SERVICE_NAME	service.name on exported telemetry (default blop-runner on the active runner)
OTEL_RESOURCE_ATTRIBUTES	Extra resource attributes, e.g. deployment.environment.name=staging
BLOP_OTEL_PROPAGATE_TO_APP	Active runner: send W3C traceparent to the app under test
BLOP_OTEL_PROPAGATE_ALLOWLIST	Active runner: comma-separated hosts allowed to receive trace context
BLOP_OTEL_TEAM	blop.team dimension on the token-usage counter

A signal with no endpoint of its own and no generic endpoint isn’t exported. You can configure traces, metrics, and logs independently. Blop supports OTLP/HTTP with Protobuf or JSON encoding; it rejects grpc explicitly instead of silently sending data with a different protocol.

Active-runner export details: runs are never sampled, metrics use delta temporality, export failures are logged and never fail a run, and shutdown will not wait more than five seconds in total for an unreachable collector.

Active runner: agent configuration

Used by the browser runner (blop test and friends); see Active browser checks.

Variable	Used for
BLOP_AGENT_PROVIDER	Default agent provider (e.g. openai, anthropic)
BLOP_AGENT_MODEL	Default model name
BLOP_AGENT_API_KEY	Default API key — takes precedence over provider-native vars
BLOP_AGENT_BASE_URL	Override the provider’s base URL (for self-hosted or proxy endpoints)

Provider-native API keys

When BLOP_AGENT_API_KEY is unset, blop falls back to the provider-native variable matching the configured provider:

Variable	Provider
OPENAI_API_KEY	openai
ANTHROPIC_API_KEY	anthropic
GEMINI_API_KEY	google
GROQ_API_KEY	groq
XAI_API_KEY	xai
OPENROUTER_API_KEY	openrouter
MISTRAL_API_KEY	mistral
CEREBRAS_API_KEY	cerebras
NVIDIA_API_KEY	nvidia

See Agent providers for setup notes and model recommendations.

Active runner: platform upload

When the required ingest values are set, the active runner uploads its run evidence automatically. Failures are logged but non-fatal. Local monitoring never requires any of these, and its SQLite data is not uploaded with a run.

Variable	Used for
BLOP_INGEST_URL	Blop Platform ingest URL
BLOP_INGEST_SECRET	Blop Platform ingest secret
BLOP_PROJECT_ID	Project the run belongs to
BLOP_TRIGGER	What triggered the run

Active runner: containerized browser

Used by --containerized to control the separate warm browser container:

Variable	Used for
BLOP_PLAYWRIGHT_IMAGE	Docker image for the Playwright container
BLOP_PLAYWRIGHT_CONTAINER	Container name to create/reuse
BLOP_CAMOUFOX_IMAGE	Prebuilt Camoufox server image override
BLOP_CAMOUFOX_CONTAINER	Camoufox container name to create/reuse (default blop-camoufox)
BLOP_CAMOUFOX_NETWORK	Shared network override; falls back to BLOP_PLAYWRIGHT_NETWORK

Debugging

Variable	Used for
BLOP_DEBUG	When set, prints stack traces on CLI errors