obscura-gateway

name

obscura-gateway

description

Use this skill when a task involves operating or changing the Obscura Gateway server: deploying or running the gateway, Dockerizing it, configuring listen/server URLs, API keys, Obscura binary paths, state directories, default stealth, browser fingerprint defaults, API behavior, child Obscura process lifecycle, server-side quotas, release packaging, or gateway/server troubleshooting. Do not use this for routine obscura-cli session/profile/cookie commands unless server behavior is being debugged.

Obscura Gateway

Use This Skill For

Obscura Gateway is the long-running control plane around the obscura browser binary. It owns state, exposes the HTTP API, enforces policy, and starts/stops short-lived obscura serve child processes.

Use this skill when the task is about the server process, deployment, Docker image, HTTP API, state files, process lifecycle, default stealth/fingerprint behavior, or release packaging.

For day-to-day client workflows such as obscura-cli session create, profile management, cookie import/export, and CDP grant commands, use the obscura-cli skill instead.

Fast Start

From the repo root:

cargo run --bin obscura-gateway -- setup
cargo run --bin obscura-gateway -- run

Docker gateway:

docker compose up --build
docker compose exec obscura-gateway sh -c "awk -F'\"' '/^api_key =/{print \$2}' /data/.obscura-gateway/config.toml"

Default local API: http://127.0.0.1:18789.

Always verify obscura is installed or configured before diagnosing gateway failures.

Server Rules

• listen_addr is where the gateway binds.
• server_url is what clients call and what CDP grants use for public URLs.
• api_key protects /v1 routes with bearer auth.
• Local state defaults to ~/.obscura-gateway.
• Docker state lives at /data/.obscura-gateway.
• default_stealth defaults to true and is inherited by sessions unless a profile or session override is provided.
• Effective stealth launches child Obscura with --stealth.
• Effective profile user agents launch child Obscura with --user-agent.
• Profile sessions fill missing identity fields with the built-in Chrome 145/macOS fingerprint defaults.
• Active sessions are live child processes; persisted DB rows cannot recover them after restart.
• A gateway restart marks previously active sessions failed.
• Child CDP ports stay on loopback and are proxied or granted by the gateway.

Reference Files

Read only the reference that matches the task:

• Gateway operations: setup, Docker, runtime configuration, state layout, API/auth, stealth/fingerprint behavior, releases, and tests.
• Gateway troubleshooting: stale sessions, Obscura binary failures, proxy/CDP server issues, and diagnostic workflow.

Validation

• Run cargo test after changing gateway code.
• Run cargo build --release --locked --bins after changing release packaging or binary layout.
• Run docker build -t obscura-gateway:local . after changing Docker files.