Skip to content

The headless browser for AI agents and web scraping

13.2 KB
Raw Blame

Runtime

OBSCURA_ALLOW_PRIVATE_NETWORK

Allow fetches to addresses in the SSRF deny-set. Off by default to block SSRF. The deny-set is defined once, in is_forbidden_ip (crates/obscura-ssrf/src/lib.rs), and covers:

Kind Ranges
Loopback and unspecified 127.0.0.0/8, 0.0.0.0/8, ::1, ::
Private (RFC 1918) 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Shared address space (RFC 6598, CGNAT) 100.64.0.0/10, which includes Tailscale addresses and the 100.100.100.200 cloud-metadata endpoint
Link-local 169.254.0.0/16 (including the 169.254.169.254 cloud-metadata endpoint), fe80::/10
IPv6 unique-local fc00::/7
Multicast and broadcast 224.0.0.0/4, 255.255.255.255, ff00::/8
Documentation and benchmarking 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 198.18.0.0/15, 2001:db8::/32, 3fff::/20
Other special-purpose IPv4 192.0.0.0/24 except 192.0.0.9 and 192.0.0.10, 192.88.99.0/24, 240.0.0.0/4
Other special-purpose IPv6 100::/64 (discard-only), 64:ff9b:1::/48 (local-use NAT64)

IPv6 addresses that embed an IPv4 address are unwrapped and the IPv4 address is checked against the rows above: IPv4-mapped (::ffff:a.b.c.d), IPv4-compatible (::a.b.c.d), NAT64 (64:ff9b::/96), 6to4 (2002::/16), and Teredo (2001::/32, server or client address).

A target on a Tailscale or other CGNAT address therefore needs this setting, just like one on a private LAN address.

The guard validates at DNS-resolution time as well as on literal hosts, so a public hostname that resolves to a forbidden address is rejected at connect time (DNS-rebinding safe), not just hosts written as raw IPs.

Truthy values: 1, true, yes, on.

OBSCURA_ALLOW_PRIVATE_NETWORK=1 obscura fetch http://localhost:8080

Per-process equivalent: --allow-private-network on any subcommand.

OBSCURA_NAV_TIMEOUT_MS

Hard ceiling on a single navigation. Default 30000 (30 seconds). Applies to Page.navigate and the CLI fetch command.

OBSCURA_NAV_TIMEOUT_MS=60000 obscura serve

OBSCURA_NAV_CHAIN_LIMIT

How many documents a navigation chain may load, the first navigation included. Default 10, which allows the requested document and nine navigations the page itself triggers via location assignments or form submissions. Raise the value for an endpoint that chains longer for good reasons, such as an SSO handover across several providers. The low default is what stops a page that resets location on every load.

A zero is raised to 1. This loads the requested document. If the page wants to chain further afterwards, the call reports an error, as at any other limit. A value the engine does not read as a number is replaced by the default. This also applies to a negative value and to a value with a trailing space.

The time budget is not tied to this limit. A longer chain usually also needs a higher OBSCURA_NAV_TIMEOUT_MS, because its default of 30 seconds applies to the whole chain and not to the individual document.

OBSCURA_NAV_CHAIN_LIMIT=20 obscura serve

OBSCURA_SCRIPT_DEADLINE_MS

Soft deadline for the complete page script-execution phase, including classic scripts and ES modules. Default 30000 (30 seconds). Raise it for a heavy SPA whose initial module is responsible for mounting an otherwise empty document. The engine also uses this value as a hard V8 watchdog budget, with a one-second grace period, so a synchronous script cannot run forever.

OBSCURA_SCRIPT_DEADLINE_MS=60000 obscura serve

OBSCURA_MODULE_BUDGET_MS

Per-module graph-loading and evaluation budget for modules that enhance an already-rendered page. Default 3000 (3 seconds). Raise it when a module such as the Vite HMR client legitimately needs longer to evaluate:

OBSCURA_MODULE_BUDGET_MS=10000 obscura serve

This shorter budget applies when the document body already contains more than 50 descendant nodes, where modules are normally progressive enhancement and should not delay navigation indefinitely. For an unmounted SPA shell, Obscura instead gives each module the full OBSCURA_SCRIPT_DEADLINE_MS budget so the app has time to mount. Module network requests remain independently bounded by OBSCURA_FETCH_TIMEOUT_MS.

OBSCURA_CDP_COMMAND_TIMEOUT_MS

Per-command V8 deadline for the CDP server. Default 60000 (60 seconds); 0 disables it. The watchdog terminates JavaScript that exceeds the budget so it can release the connection's V8 lock. It cannot preempt native Rust work. Keep this budget above OBSCURA_NAV_TIMEOUT_MS.

OBSCURA_CDP_COMMAND_TIMEOUT_MS=30000 obscura serve

OBSCURA_CDP_TOKEN

Bearer token for the CDP discovery and WebSocket endpoints. It is optional on loopback. A non-loopback bind is refused unless this is set to at least 32 bytes. Pass it as Authorization: Bearer <token> in the CDP client's headers.

OBSCURA_CDP_TOKEN="$(openssl rand -hex 32)" obscura serve --host 0.0.0.0

OBSCURA_CDP_ALLOWED_ORIGINS

Comma-separated Origin allowlist for CDP discovery and WebSocket requests. Without it, clients that omit Origin or send the endpoint's own HTTP origin are accepted. Origins with a different scheme, hostname, or port are refused with an actionable 403, including other loopback applications. Forwarded workers compare against the client-facing request authority.

List another application's exact origin to grant it access. Matching is case-insensitive. * allows every origin, including null, and removes the browser-origin boundary; avoid it for untrusted pages. Host validation and OBSCURA_CDP_TOKEN authentication still apply to allowlisted origins.

OBSCURA_CDP_ALLOWED_ORIGINS="https://tunnel.example" obscura serve

OBSCURA_FETCH_TIMEOUT_MS

Request timeout for scripted fetch(), XMLHttpRequest, and ES-module loads. Without it a request to a server that accepts the connection but never responds (including a CORS preflight) hangs forever and the XHR is stuck with no completion event. Default 30000 (30 seconds).

OBSCURA_FETCH_TIMEOUT_MS=15000 obscura serve

OBSCURA_PROXY

Default proxy URL for serve and direct obscura-worker invocations. The scrape command passes its --proxy value to workers through this variable; an unset --proxy clears the inherited worker value. Use --proxy for fetch, scrape, and mcp.

OBSCURA_PROXY=http://proxy.example.com:8080 obscura serve

Resource limits

Values below are non-negative integers. Byte limits use bytes, not MiB.

Variable Default Effect
OBSCURA_FETCH_MAX_BODY_BYTES 104857600 for JS fetch/XHR; 33554432 for modules Maximum buffered response size. Setting it overrides both defaults.
OBSCURA_NETWORK_BODY_BUFFER_ENTRIES 128 Maximum retained response bodies in each page/runtime cache. Zero disables retention.
OBSCURA_NETWORK_BODY_BUFFER_BYTES 2097152 Largest individual response body retained for CDP retrieval. Zero disables retention; this is not a total-cache byte limit.
OBSCURA_IO_STREAM_MAX_ENTRIES 32 Maximum open CDP response-body streams per connection.
OBSCURA_IO_STREAM_MAX_BYTES 268435456 Total bytes retained by those streams. Oldest streams are evicted when a limit is exceeded.
OBSCURA_MAX_LIVE_FRAMES 64 Maximum live child frames per page, including initial realms awaiting adoption.
OBSCURA_FRAME_MESSAGE_QUEUE_ENTRIES 4096 Maximum queued cross-frame messages.
OBSCURA_FRAME_MESSAGE_QUEUE_BYTES 8388608 Maximum bytes in the cross-frame message queue.

Disabling response-body retention does not disable network events. Reading an evicted CDP body or stream returns an error.

Rendering

These settings require a render-enabled build.

Variable Default Effect
OBSCURA_SHOT_W / OBSCURA_SHOT_H 1280 / 720 CLI screenshot viewport in CSS pixels, set before navigation.
OBSCURA_SHOT_ANIMATION_TIME_MS Live timeline Sample CSS animations at a finite, non-negative time for a CLI screenshot.
OBSCURA_RENDER_RESOURCE_DEADLINE_MS 3000 Resource preparation budget before CLI/CDP screenshots, in milliseconds.
OBSCURA_RENDER_RESOURCE_WARMUP_MS 1000 Resource preparation budget before navigation scripts, in milliseconds.
OBSCURA_RENDER_RESOURCE_POST_SCRIPT_WARMUP_MS 1000 Resource preparation budget after navigation scripts, in milliseconds.
OBSCURA_RENDER_RESOURCE_SETTLE_WARMUP_MS 1000 Resource preparation budget after settling, bounded by its remaining time.

For example:

OBSCURA_SHOT_W=1440 OBSCURA_SHOT_H=1000 \
  obscura fetch https://example.com --screenshot page.png

Stealth and identity

These tune the browser identity the engine presents so it stays internally consistent. See Configure stealth and proxies for the full picture.

OBSCURA_BLOCK_TRACKERS

Controls the tracker blocklist used by the stealth HTTP transport. It is on by default so --stealth retains its current privacy-first behavior. Set it to 0, false, no, or off to keep the stealth TLS/browser fingerprint while allowing tracker requests.

The setting is read when a stealth client is created. Values are case-insensitive and surrounding whitespace is ignored; unset, empty, and unrecognized values keep blocking enabled. Non-stealth transport settings and SSRF protection are unchanged.

OBSCURA_BLOCK_TRACKERS=0 obscura --stealth fetch https://example.com

OBSCURA_TIMEZONE

Pins the process timezone before V8/ICU reads it, so Date (getTimezoneOffset, toString) and Intl.DateTimeFormat report one consistent zone. Default Europe/Berlin. Set it to match the exit IP's region.

OBSCURA_TIMEZONE=America/New_York obscura serve

OBSCURA_GEOLOCATION

Override the coordinates the navigator.geolocation shim reports, as lat,lon. Without it the shim reports a fixed default. Keep it consistent with OBSCURA_TIMEZONE and the proxy region.

OBSCURA_GEOLOCATION="40.7128,-74.0060" obscura serve

OBSCURA_PROFILE

Pin a specific browser profile from the built-in pool by index (0-based). Each profile keeps navigator.platform, userAgentData, and the UA string internally consistent. Without it a single stable profile is used.

OBSCURA_PROFILE=2 obscura serve

OBSCURA_ROTATE_PROFILE

Opt into picking a random profile per browser context instead of the stable default. Leave it off when you pin a TLS fingerprint, proxy region, or timezone, since a rotated profile would no longer match those.

OBSCURA_ROTATE_PROFILE=1 obscura serve

MCP

OBSCURA_STORAGE_DIR

Persistent profile directory for MCP. Equivalent to passing --storage-dir before the mcp subcommand. See Persist cookies and storage.

OBSCURA_STORAGE_DIR=./obscura-data obscura mcp

OBSCURA_MCP_ALLOWED_ORIGINS

Comma-separated Origin allowlist for the HTTP MCP transport (obscura mcp --http). Browser requests are refused by default; when set, only listed origins are accepted. Native clients without an Origin header pass the origin check. If OBSCURA_MCP_TOKEN is set, they still need that token.

OBSCURA_MCP_TOKEN="$(openssl rand -hex 32)" \
OBSCURA_MCP_ALLOWED_ORIGINS="https://app.example.com" \
  obscura mcp --http --host 0.0.0.0

OBSCURA_MCP_TOKEN

Bearer token for MCP HTTP requests. It is optional on loopback. A non-loopback bind is refused unless this is set to at least 32 bytes.

OBSCURA_MCP_TOKEN="$(openssl rand -hex 32)" obscura mcp --http --host 0.0.0.0

Logging

RUST_LOG

Standard tracing filter. Common settings:

RUST_LOG=obscura=info obscura serve
RUST_LOG=obscura=debug obscura serve
RUST_LOG=obscura_cdp=trace,obscura_browser=debug obscura serve

--verbose selects debug-level logging unless RUST_LOG supplies a filter. The default filter is warn; --quiet selects off.

Build

OPENSSL_NO_VENDOR

Forces cargo build to use the system OpenSSL instead of compiling the vendored copy. Set to 1 on hosts where the vendored OpenSSL fails (older VPS with AVX-512 issues).

OPENSSL_NO_VENDOR=1 cargo build --release -p obscura-cli --bins --features render

V8

V8 flags are passed via --v8-flags, not environment variables:

obscura --v8-flags "--max-old-space-size=2048 --expose-gc" serve

Defaults are --max-old-space-size=4096 --max-semi-space-size=4 --optimize-for-size on 64-bit systems. In the current V8, --optimize-for-size overrides the requested semi-space cap to 1 MiB, not 4 MiB. The old-generation ceiling remains 4 GB.

User flags are appended after the defaults, but V8 applies flag implications afterwards. To change the young-generation cap, also disable size optimization, for example obscura --v8-flags "--no-optimize-for-size --max-semi-space-size=8" serve. This can reduce GC CPU at the cost of more memory; measure the complete workload before adopting it. Use --v8-flags "--print-flag-values" to inspect the effective settings after V8 initialization.

HTTP proxy environment

Obscura does not honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY. Use --proxy; OBSCURA_PROXY is available for serve and direct worker invocations as described above.