### Setup Obscura Server and Install Playwright

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-with-Playwright

Start the Obscura server and install the Playwright library.

```bash
obscura serve --port 9222
npm install playwright
```

--------------------------------

### start_with_full_options()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with all configuration options, including user agent and storage directory. This provides the most flexibility in server setup.

```APIDOC
## start_with_full_options()

### Description
Starts a CDP server with all configuration options, including user agent and storage directory. This provides the most flexibility in server setup.

### Method
`async fn`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| port | u16 | Yes | — | TCP port to listen on |
| proxy | Option<String> | No | None | HTTP/SOCKS5 proxy URL |
| stealth | bool | No | false | Enable anti-detection mode |
| user_agent | Option<String> | No | Chrome default | Custom User-Agent string |
| storage_dir | Option<PathBuf> | No | None | Directory for persistent storage (cookies) |

### Returns
`anyhow::Result<()>`

### Example
```rust
use std::path::PathBuf;

obscura_cdp::start_with_full_options(
    9222,
    None,
    true,
    Some("Custom-UA/1.0".to_string()),
    Some(PathBuf::from("/tmp/browser-storage")),
).await?;
```
```

--------------------------------

### Obscura Rust Quickstart Example

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-as-a-Rust-library

A basic example demonstrating how to initialize the Obscura browser, navigate to a page, and extract information like URL, HTML content, element text, and page title. Requires Tokio runtime and anyhow for error handling.

```rust
use obscura::Browser;
use std::time::Duration;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::builder()
        .stealth(true)
        .build()?;

    let mut page = browser.new_page().await?;
    page.goto("https://example.com").await?;

    println!("URL: {}", page.url());
    println!("HTML bytes: {}", page.content().len());

    let el = page.wait_for_selector("h1", Duration::from_secs(5)).await?;
    println!("Heading: {}", el.text());

    let title = page.evaluate("document.title");
    println!("Title: {}", title);

    Ok(())
}
```

--------------------------------

### Obscura Serve Command Examples

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cli.md

Demonstrates various ways to start the Obscura Chrome DevTools Protocol WebSocket server, including basic startup, network exposure, stealth mode, and proxy/storage configuration.

```bash
obscura serve
```

```bash
obscura serve --host 0.0.0.0
```

```bash
obscura serve --stealth
```

```bash
obscura serve --proxy http://127.0.0.1:8080 --storage-dir /var/storage
```

--------------------------------

### Navigation Examples

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/lifecycle.md

Provides examples of how to perform navigation with different wait conditions.

```APIDOC
## Navigation Examples

### Basic Navigation with Default Wait

```rust
page.navigate("https://example.com").await?;
// Waits for `load` event
```

---

### Fast Navigation (DOM Ready)

```rust
use obscura_browser::WaitUntil;

page.navigate_with_wait(
    "https://example.com",
    WaitUntil::DomContentLoaded,
).await?;
// Returns as soon as DOM is parsed, before scripts run
```

---

### Complete Page Load

```rust
use obscura_browser::WaitUntil;

page.navigate_with_wait(
    "https://example.com",
    WaitUntil::NetworkIdle0,
).await?;
// Waits for all network activity to stop
```

---

### Manual Polling

```rust
loop {
    if page.lifecycle.is_loaded() {
        break;
    }
    page.settle(100).await;
}
```

---
```

--------------------------------

### start()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server on the default host (127.0.0.1) with minimal configuration. This function blocks indefinitely if successful.

```APIDOC
## start()

### Description
Starts a CDP server on the default host (127.0.0.1) with minimal configuration. This function blocks indefinitely if successful.

### Method
`async fn`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| port | u16 | Yes | — | TCP port to listen on (e.g., 9222) |

### Returns
`anyhow::Result<()>` — Never returns if successful; blocks indefinitely

### Example
```rust
use obscura_cdp;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    obscura_cdp::start(9222).await
}
```
```

--------------------------------

### Obscura CDP Server Usage Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/modules.md

Starts the Chrome DevTools Protocol server with specified options, including port, proxy, stealth mode, and user agent. Requires the tokio runtime and anyhow for error handling.

```rust
use obscura_cdp;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Start CDP server
    obscura_cdp::start_with_full_options(
        9222,                      // port
        None,                       // proxy
        true,                       // stealth
        None,                       // user_agent
        None,                       // storage_dir
    ).await
}
```

--------------------------------

### Start Obscura Serve Basic

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Obscura CDP WebSocket server on the default port.

```bash
obscura serve
```

--------------------------------

### Install Obscura and Puppeteer Core

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-with-Puppeteer

Install Obscura to serve as a debugging endpoint and `puppeteer-core` for connecting to it.

```bash
obscura serve --port 9222
npm install puppeteer-core
```

--------------------------------

### Start CDP Server with Full Options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with all available configuration options, including proxy, stealth mode, custom user agent, and persistent storage directory.

```rust
use std::path::PathBuf;

obscura_cdp::start_with_full_options(
    9222,
    None,
    true,
    Some("Custom-UA/1.0".to_string()),
    Some(PathBuf::from("/tmp/browser-storage")),
).await?;
```

--------------------------------

### CDP Parity Test Example

Source: https://github.com/h4ckf0r0day/obscura/wiki/Testing-and-debugging

An example of a Rust test case for CDP parity. It sets up an environment variable, starts a server, creates a CDP context, and navigates a page.

```rust
#[tokio::test(flavor = "current_thread")]
async fn my_test() {
    std::env::set_var("OBSCURA_ALLOW_PRIVATE_NETWORK", "1");
    let url = serve_once().await;
    let mut ctx = CdpContext::new();
    let page_id = ctx.create_page();
    let session_id = "session-1";
    ctx.sessions.insert(session_id.to_string(), page_id.clone());

    cdp(&mut ctx, 1, "Page.navigate", json!({"url": url}), session_id).await;
    // assertions
}
```

--------------------------------

### Async Tokio Entry Point

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/modules.md

Example of setting up an asynchronous main function using the Tokio runtime.

```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Your code here
    Ok(())
}
```

--------------------------------

### Start CDP Server with Options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with proxy and stealth mode enabled. The proxy can be an HTTP or SOCKS5 URL, and stealth mode enables anti-detection features.

```rust
obscura_cdp::start_with_options(
    9222,
    Some("http://127.0.0.1:8080".to_string()),
    true,
).await?;
```

--------------------------------

### Start CDP Server with Full Serve Options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with all configuration options, including private network access control. This allows the server to fetch from loopback and private network addresses when enabled.

```rust
pub async fn start_with_full_serve_options(
    port: u16,
    host: &str,
    proxy: Option<String>,
    stealth: bool,
    user_agent: Option<String>,
    allow_file_access: bool,
    storage_dir: Option<std::path::PathBuf>,
    allow_private_network: bool,
) -> anyhow::Result<()>
```

```rust
use std::path::PathBuf;

obscura_cdp::start_with_full_serve_options(
    9222,
    "0.0.0.0",
    None,
    true,
    Some("Custom-UA/1.0".to_string()),
    false,
    Some(PathBuf::from("/var/obscura/storage")),
    true, // Allow 127.0.0.1, 192.168.x.x, etc.
).await?;
```

--------------------------------

### Start CDP Server with Host and Full Options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server on a specific host and port with all configuration options. This allows binding to non-localhost interfaces, useful for Docker deployments.

```rust
// Listen on all interfaces (Docker)
obscura_cdp::start_with_host(
    9222,
    "0.0.0.0",
    None,
    false,
    None,
    None,
).await?;
```

--------------------------------

### Run Obscura via Docker

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/README.md

Start the Obscura service using Docker, exposing the DevTools port. This is an alternative installation method.

```bash
docker run -p 9222:9222 h4ckf0r0day/obscura obscura serve --host 0.0.0.0
```

--------------------------------

### Start Obscura Serve with Persistent Storage

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Obscura CDP WebSocket server and configures a directory for persistent cookie storage.

```bash
obscura serve --storage-dir /var/obscura/storage
```

--------------------------------

### Start Obscura Serve with All Options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Obscura CDP WebSocket server with a comprehensive set of options including port, host, proxy, stealth mode, custom user agent, storage directory, and private network access.

```bash
obscura serve --port 9222 --host 0.0.0.0 --proxy socks5://proxy:1080 \
  --stealth --user-agent "Custom/1.0" --storage-dir /var/storage \
  --allow-private-network
```

--------------------------------

### Start Obscura Server

Source: https://github.com/h4ckf0r0day/obscura/wiki/Connect-Puppeteer-or-Playwright

Start the Obscura server on a specified port. The server will listen for WebSocket connections.

```bash
obscura serve --port 9222
```

--------------------------------

### Install Obscura CLI System-Wide

Source: https://github.com/h4ckf0r0day/obscura/wiki/Build-from-source

Install the Obscura command-line interface to your system's PATH using Cargo.

```bash
cargo install --path crates/obscura-cli
```

--------------------------------

### MCP Server Start

Source: https://github.com/h4ckf0r0day/obscura/blob/main/README.md

Starts the Model Context Protocol (MCP) server, which exposes browser automation tools to AI agents. Supports both stdio and HTTP transports.

```APIDOC
## MCP (Model Context Protocol)

Obscura ships an MCP server that exposes browser automation tools to AI agents (Claude Desktop, Cursor, etc.).

### Start

**stdio** (default) — for Claude Desktop and MCP clients that launch a subprocess:

```bash
obscura mcp
```

**HTTP** — for clients that connect over the network:

```bash
obscura mcp --http --port 8080
# endpoint: http://127.0.0.1:8080/mcp
```

Optional flags (both transports):

| Flag | Description |
|------|-------------|
| `--proxy <URL>` | HTTP/SOCKS5 proxy |
| `--user-agent <UA>` | Custom User-Agent string |
| `--stealth` | Enable anti-detection mode |
```

--------------------------------

### start_with_options()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with proxy and stealth mode options. This function allows for more granular control over the server's behavior.

```APIDOC
## start_with_options()

### Description
Starts a CDP server with proxy and stealth mode options. This function allows for more granular control over the server's behavior.

### Method
`async fn`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| port | u16 | Yes | — | TCP port to listen on |
| proxy | Option<String> | No | None | HTTP/SOCKS5 proxy URL (e.g., `http://127.0.0.1:8080`) |
| stealth | bool | No | false | Enable anti-detection mode (fingerprinting randomization + tracker blocking) |

### Returns
`anyhow::Result<()>`

### Example
```rust
obscura_cdp::start_with_options(
    9222,
    Some("http://127.0.0.1:8080".to_string()),
    true,
).await?;
```
```

--------------------------------

### Start CDP Server with File Access Control

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with control over file:// navigation security. Enable file:// access only when local HTML testing is required.

```rust
pub async fn start_with_host_and_security(
    port: u16,
    host: &str,
    proxy: Option<String>,
    stealth: bool,
    user_agent: Option<String>,
    allow_file_access: bool,
    storage_dir: Option<std::path::PathBuf>,
) -> anyhow::Result<()>
```

```rust
// Allow local file access for testing
obscura_cdp::start_with_host_and_security(
    9222,
    "127.0.0.1",
    None,
    false,
    None,
    true, // Allow file:// URLs
    None,
).await?;
```

--------------------------------

### start_with_host()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server on a specific host with all configuration options. This allows binding to non-localhost interfaces, which is useful in containerized environments.

```APIDOC
## start_with_host()

### Description
Starts a CDP server on a specific host with all configuration options. This allows binding to non-localhost interfaces, which is useful in containerized environments.

### Method
`async fn`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| port | u16 | Yes | — | TCP port to listen on |
| host | &str | Yes | — | Host to bind to (e.g., `127.0.0.1`, `0.0.0.0`, or an IP address) |
| proxy | Option<String> | No | None | HTTP/SOCKS5 proxy URL |
| stealth | bool | No | false | Enable anti-detection mode |
| user_agent | Option<String> | No | Chrome default | Custom User-Agent string |
| storage_dir | Option<PathBuf> | No | None | Directory for persistent storage |

### Returns
`anyhow::Result<()>`

### Example
```rust
// Listen on all interfaces (Docker)
obscura_cdp::start_with_host(
    9222,
    "0.0.0.0",
    None,
    false,
    None,
    None,
).await?;
```
```

--------------------------------

### Install Playwright

Source: https://github.com/h4ckf0r0day/obscura/wiki/Connect-Puppeteer-or-Playwright

Install the playwright package for Playwright automation.

```bash
npm install playwright
```

--------------------------------

### Start Obscura Serve with File Access

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Obscura CDP WebSocket server and allows CDP clients to navigate to `file://` URLs.

```bash
obscura serve --allow-file-access
```

--------------------------------

### start_with_full_serve_options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with all configuration options, including private network access control. When `allow_private_network` is true, the server can fetch from loopback, RFC1918, and link-local addresses.

```APIDOC
## start_with_full_serve_options()

### Description
Starts a CDP server with all configuration options including private network access control. When `allow_private_network` is true, the server can fetch from loopback, RFC1918, and link-local addresses.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
`pub async fn start_with_full_serve_options(
    port: u16,
    host: &str,
    proxy: Option<String>,
    stealth: bool,
    user_agent: Option<String>,
    allow_file_access: bool,
    storage_dir: Option<std::path::PathBuf>,
    allow_private_network: bool,
) -> anyhow::Result<()>`

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| port | u16 | Yes | — | TCP port to listen on |
| host | &str | Yes | — | Host to bind to |
| proxy | Option<String> | No | None | HTTP/SOCKS5 proxy URL |
| stealth | bool | No | false | Enable anti-detection mode |
| user_agent | Option<String> | No | Chrome default | Custom User-Agent string |
| allow_file_access | bool | No | false | Allow `file://` navigation via CDP |
| storage_dir | Option<PathBuf> | No | None | Directory for persistent storage |
| allow_private_network | bool | No | false | Allow access to private network addresses |

### Returns
`anyhow::Result<()>`

### Example
```rust
use std::path::PathBuf;

obscura_cdp::start_with_full_serve_options(
    9222,
    "0.0.0.0",
    None,
    true,
    Some("Custom-UA/1.0".to_string()),
    false,
    Some(PathBuf::from("/var/obscura/storage")),
    true, // Allow 127.0.0.1, 192.168.x.x, etc.
).await?;
```
```

--------------------------------

### Install Playwright Core

Source: https://github.com/h4ckf0r0day/obscura/blob/main/README.md

Installs the playwright-core npm package, necessary for connecting to a CDP server.

```bash
npm install playwright-core
```

--------------------------------

### Download and Extract Obscura Binary

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/README.md

Download the prebuilt binary for Linux and extract it. This is the first step for manual installation.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
```

--------------------------------

### browser_navigate Tool Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Navigate to a specified URL and wait for the page to load. Supports different wait conditions.

```json
Tool: browser_navigate
Input: {"url": "https://example.com", "waitUntil": "networkidle0"}
Output: { "success": true }
```

--------------------------------

### Install Puppeteer Core

Source: https://github.com/h4ckf0r0day/obscura/wiki/Connect-Puppeteer-or-Playwright

Install the puppeteer-core package, which is required to connect to a remote browser instance.

```bash
npm install puppeteer-core
```

--------------------------------

### Install Obscura from Arch Linux AUR

Source: https://github.com/h4ckf0r0day/obscura/wiki/Installation

Install Obscura using the yay AUR helper for Arch Linux systems.

```bash
yay -S obscura-browser
```

--------------------------------

### Enable and Monitor Obscura Systemd Service

Source: https://github.com/h4ckf0r0day/obscura/wiki/Run-in-production-at-scale

Enables the Obscura service to start on boot and starts it immediately, then shows how to view its logs in real-time.

```bash
systemctl enable --now obscura
journalctl -fu obscura
```

--------------------------------

### Lifecycle Timeline Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/lifecycle.md

Illustrates a typical timeline of lifecycle states for a web page during navigation and loading.

```APIDOC
## Lifecycle Timeline Example

For a typical web page:

```
Navigation Start
↓
Loading (HTML fetch starts)
↓ (~50ms)
DomContentLoaded (parser done, deferred scripts start)
↓ (~200ms)
Loaded (all parser-blocking scripts done, load event fired)
↓ (~500ms)
NetworkIdle2 (≤2 requests in flight)
↓ (~800ms)
NetworkIdle0 (all requests complete)
↓
Idle (no further activity)
```

---
```

--------------------------------

### Start CDP Server

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server on the default host (127.0.0.1) on the specified TCP port. This function blocks indefinitely if successful.

```rust
use obscura_cdp;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    obscura_cdp::start(9222).await
}
```

--------------------------------

### Start Obscura Serve Accessible

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Obscura CDP WebSocket server and binds it to all network interfaces, making it accessible from other machines. Useful for Docker deployments.

```bash
obscura serve --host 0.0.0.0
```

--------------------------------

### Start CDP server with all options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Chrome DevTools Protocol (CDP) server in Rust with comprehensive configuration, including port, host, proxy, stealth mode, user agent, file access, storage directory, and private network allowance.

```rust
use obscura_cdp;

// Start with all options
obscura_cdp::start_with_full_serve_options(
    9222,           // port
    "0.0.0.0",      // host
    Some("http://proxy:8080".to_string()), // proxy
    true,           // stealth
    Some("Custom-UA/1.0".to_string()),     // user_agent
    true,           // allow_file_access
    Some(PathBuf::from("/var/storage")),
    true,           // allow_private_network
).await?;
```

--------------------------------

### Build with System OpenSSL

Source: https://github.com/h4ckf0r0day/obscura/wiki/Build-from-source

If the build fails due to vendored OpenSSL on older systems, use this command to build against the system's OpenSSL installation.

```bash
OPENSSL_NO_VENDOR=1 cargo build --release
```

--------------------------------

### Use with Claude AI (MCP)

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/README.md

Starts an MCP server for Obscura and provides configuration details for Claude Desktop.

```bash
# Start MCP server
obscura mcp --http --port 8080

# Configure in Claude Desktop
# { "mcpServers": { "obscura": { "command": "obscura", "args": ["mcp"] } } }
```

--------------------------------

### Start MCP server in HTTP mode

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cli.md

Launch the Model Context Protocol server as an HTTP service, specifying the host and port for network access.

```bash
obscura mcp --http --port 8080
```

--------------------------------

### Start Obscura Serve with Proxy and Stealth

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Starts the Obscura CDP WebSocket server with a specified port, HTTP proxy, and anti-detection stealth mode enabled.

```bash
obscura serve --port 9222 --proxy http://127.0.0.1:8080 --stealth
```

--------------------------------

### Run Obscura MCP Server (Stdio)

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-the-MCP-server

Starts the Obscura MCP server using standard input/output, suitable for direct client integration.

```bash
obscura mcp
```

--------------------------------

### Download and Install Obscura for Linux x86_64

Source: https://github.com/h4ckf0r0day/obscura/wiki/Installation

Use curl to download the binary, tar to extract it, and then run the version command. Ensure you are on an x86_64 Linux architecture.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura --version
```

--------------------------------

### Download and Install Obscura for Linux ARM64

Source: https://github.com/h4ckf0r0day/obscura/wiki/Installation

Use curl to download the binary, tar to extract it, and then run the version command. Ensure you are on an ARM64 Linux architecture.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-linux.tar.gz
tar xzf obscura-aarch64-linux.tar.gz
./obscura --version
```

--------------------------------

### Start MCP Server with stdio Transport

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Use this command to start the MCP server for clients that launch subprocesses, like Claude Desktop or Cursor. Configure your client's settings to use this command.

```bash
obscura mcp
```

```json
{
  "mcpServers": {
    "obscura": {
      "command": "obscura",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Serve for Login Once, Scrape Many

Source: https://github.com/h4ckf0r0day/obscura/wiki/Persist-cookies-and-storage

Run the Obscura server with a specific --storage-dir to perform a login flow once. Subsequent runs using the same directory will start logged in.

```bash
obscura serve --storage-dir ./session-1
```

--------------------------------

### Obscura Scrape Example with Stdin

Source: https://github.com/h4ckf0r0day/obscura/wiki/CLI-reference

Demonstrates how to pipe URLs from stdin to the `obscura scrape` command for parallel processing.

```bash
cat urls.txt | obscura scrape - --eval "document.title" --concurrency 20
```

--------------------------------

### Download and Install Obscura for macOS Intel

Source: https://github.com/h4ckf0r0day/obscura/wiki/Installation

Use curl to download the binary, tar to extract it, and then run the version command. This is for macOS on Intel (x86_64) architecture.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-macos.tar.gz
tar xzf obscura-x86_64-macos.tar.gz
./obscura --version
```

--------------------------------

### browser_click Tool Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Click an HTML element identified by a CSS selector. Returns success or an error.

```json
Tool: browser_click
Input: {"selector": "button.submit"}
Output: { "success": true }
```

--------------------------------

### obscura serve

Source: https://github.com/h4ckf0r0day/obscura/blob/main/README.md

Starts a Chrome DevTools Protocol WebSocket server. Allows remote control of the browser instance.

```APIDOC
## CLI: `obscura serve`

Start a CDP WebSocket server.

### Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--port` | `9222` | WebSocket port |
| `--proxy` | — | HTTP/SOCKS5 proxy URL |
| `--stealth` | off | Enable anti-detection + tracker blocking |
| `--workers` | `1` | Number of parallel worker processes |
| `--obey-robots` | off | Respect robots.txt |
```

--------------------------------

### Navigate Page with Obscura Rust API

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/README.md

Example of navigating to a page using the Obscura Rust API.

```rust
Page::navigate().await?
```

--------------------------------

### Get Document Root Node

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/endpoints.md

Retrieves the root node of the document. This is typically the starting point for DOM traversal and manipulation.

```json
{
  "root": {
    "nodeId": 1,
    "nodeName": "#document",
    "nodeType": 9,
    "childNodeCount": 1,
    "children": [
      { "nodeId": 2, "nodeName": "HTML", "nodeType": 1 }
    ]
  }
}
```

--------------------------------

### Serve with Debug Logging

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cli.md

Start the Obscura server with verbose logging enabled on a specified port. Useful for debugging server-side operations.

```bash
RUST_LOG=debug obscura serve --port 9222
```

--------------------------------

### Start MCP server with stealth and proxy

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cli.md

Configure the Model Context Protocol server to use anti-detection measures ('stealth' mode) and route traffic through an HTTP proxy.

```bash
obscura mcp --http --stealth --proxy http://127.0.0.1:8080
```

--------------------------------

### browser_evaluate Tool Examples

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Evaluate JavaScript expressions within the browser context and return the result. Can be used to get counts or extract data.

```javascript
Tool: browser_evaluate
Input: {"expression": "document.querySelectorAll('a').length"}
Output: 42
```

```javascript
Tool: browser_evaluate
Input: {"expression": "Array.from(document.querySelectorAll('h1')).map(h => h.textContent)"}
Output: ["Title 1", "Title 2"]
```

--------------------------------

### Run Obscura MCP Server (HTTP)

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-the-MCP-server

Starts the Obscura MCP server with HTTP enabled on a specified port for remote or shared access.

```bash
obscura mcp --http --port 3000
```

--------------------------------

### Run Obscura MCP Server (Stealth and Proxy)

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-the-MCP-server

Starts the Obscura MCP server with stealth mode enabled and configured to use a proxy server.

```bash
obscura mcp --stealth --proxy http://proxy.example.com:8080
```

--------------------------------

### Obscura Browser Usage Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/modules.md

Demonstrates creating a browser context, opening a new page, navigating to a URL, and evaluating JavaScript to retrieve the page title. Requires the tokio runtime.

```rust
use obscura_browser::{BrowserContext, Page, WaitUntil};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create browser context
    let context = Arc::new(
        BrowserContext::with_options(
            "ctx-1".to_string(),
            None,
            false, // stealth
        )
    );

    // Create page
    let mut page = Page::new("page-1".to_string(), context);

    // Navigate
    page.navigate_with_wait(
        "https://example.com",
        WaitUntil::NetworkIdle0,
    ).await?;

    // Evaluate JavaScript
    let title = page.evaluate("document.title");
    println!("Title: {}", title);

    Ok(())
}
```

--------------------------------

### Start Obscura CDP Server with Verbose Logging

Source: https://github.com/h4ckf0r0day/obscura/wiki/Testing-and-debugging

Launch the Obscura CDP server on a specific port with verbose logging enabled. This is useful for detailed debugging of server interactions.

```bash
obscura serve --port 9222 --verbose
```

--------------------------------

### Download and Install Obscura for macOS Apple Silicon

Source: https://github.com/h4ckf0r0day/obscura/wiki/Installation

Use curl to download the binary, tar to extract it, and then run the version command. This is for macOS on Apple Silicon (ARM64) architecture.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-macos.tar.gz
tar xzf obscura-aarch64-macos.tar.gz
./obscura --version
```

--------------------------------

### Obscura Fetch Command Examples

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cli.md

Shows how to fetch and render a single web page using the Obscura CLI, covering various options like JavaScript evaluation, wait conditions, output formats, and file saving.

```bash
obscura fetch https://example.com --eval "document.title"
```

```bash
obscura fetch https://example.com --wait-until networkidle0
```

```bash
obscura fetch https://example.com --dump markdown
```

```bash
obscura fetch https://example.com --dump links
```

```bash
obscura fetch https://example.com --wait-until domcontentloaded
```

```bash
obscura fetch https://example.com --dump html --output page.html
```

```bash
obscura fetch https://example.com --proxy http://127.0.0.1:8080
```

```bash
obscura fetch https://api.example.com --eval "fetch('/data').then(r=>r.json())" --dump original
```

```bash
obscura fetch https://example.com --dump text --quiet > content.txt
```

--------------------------------

### Obscura CLI Structure Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/modules.md

Illustrates the structure of the command-line interface arguments and commands within the obscura_cli crate. This crate is intended for binary use, not direct library import.

```rust
// From obscura_cli main.rs
struct Args {
    verbose: bool,
    command: Option<Command>,
    port: u16,
    proxy: Option<String>,
    ...
}

enum Command {
    Serve { ... },
    Fetch { ... },
    Scrape { ... },
    Mcp { ... },
}
```

--------------------------------

### Create BrowserContext with All Options and Storage

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/browser-context.md

Use BrowserContext::with_storage_full() to create a context with all available options: proxy, stealth, user-agent, and persistent cookie storage.

```rust
use std::path::PathBuf;

let context = BrowserContext::with_storage_full(
    "ctx-1".to_string(),
    Some("http://127.0.0.1:8080".to_string()),
    true,
    Some("Custom-UA/1.0".to_string()),
    Some(PathBuf::from("/tmp/browser-storage")),
);
```

--------------------------------

### Smoke Test Obscura Installation

Source: https://github.com/h4ckf0r0day/obscura/wiki/Installation

Perform a basic test to verify the Obscura installation by fetching the title of a webpage. The expected output is provided.

```bash
./obscura fetch https://example.com --eval "document.title"
```

--------------------------------

### Start Obscura CDP Server with Stealth Mode

Source: https://github.com/h4ckf0r0day/obscura/blob/main/README.md

Starts the Obscura CDP server with stealth mode enabled for anti-detection and tracker blocking.

```bash
# With stealth mode (anti-detection + tracker blocking)
obscura serve --port 9222 --stealth
```

--------------------------------

### Create BrowserContext with Full Options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/browser-context.md

Use BrowserContext::with_full_options() to create a context with proxy, stealth mode, and a custom user-agent string.

```rust
let context = BrowserContext::with_full_options(
    "ctx-1".to_string(),
    None,
    false,
    Some("Mozilla/5.0 (Custom) AppleWebKit/537.36".to_string()),
);
```

--------------------------------

### BrowserContext Initialization

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/modules.md

Demonstrates how to create a BrowserContext, which is typically used to indirectly access the ObscuraHttpClient.

```rust
let context = BrowserContext::with_options("ctx-1".to_string(), proxy_url, stealth);
// context.http_client is Arc<ObscuraHttpClient>
```

--------------------------------

### Start Obscura CDP Server

Source: https://github.com/h4ckf0r0day/obscura/blob/main/skills/obscura/SKILL.md

Starts the Obscura Chrome DevTools Protocol (CDP) server on a specified port. This allows tools like Puppeteer and Playwright to connect to Obscura as if it were a Chrome browser.

```bash
/tmp/obscura-target/debug/obscura serve --port 9222
```

--------------------------------

### browser_type Tool Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Append text to an input field by its CSS selector, simulating typing.

```json
Tool: browser_type
Input: {"selector": "input#search", "text": "python web scraping"}
Output: { "success": true }
```

--------------------------------

### BrowserContext::with_storage_full()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/browser-context.md

Creates a browser context with all available options, including proxy, stealth mode, custom user-agent, and disk-based cookie persistence.

```APIDOC
## BrowserContext::with_storage_full()

### Description
Creates a context with all options including proxy, stealth, user-agent, and storage.

### Method
Rust function call

### Parameters
#### Path Parameters
- **id** (String) - Required - Unique identifier for this context
- **proxy_url** (Option<String>) - Optional - HTTP/SOCKS5 proxy URL
- **stealth** (bool) - Optional - Enable anti-detection mode
- **user_agent** (Option<String>) - Optional - Custom User-Agent string
- **storage_dir** (Option<PathBuf>) - Optional - Directory path for cookie persistence

### Returns
- **BrowserContext**

### Example
```rust
use std::path::PathBuf;

let context = BrowserContext::with_storage_full(
    "ctx-1".to_string(),
    Some("http://127.0.0.1:8080".to_string()),
    true,
    Some("Custom-UA/1.0".to_string()),
    Some(PathBuf::from("/tmp/browser-storage")),
);
```
```

--------------------------------

### start_with_host_and_security

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Starts a CDP server with file:// navigation security control. This function allows for controlling whether CDP clients can navigate to `file://` URLs, which is disabled by default to prevent local file read attacks. It's useful for local HTML testing when enabled.

```APIDOC
## start_with_host_and_security()

### Description
Starts a CDP server with file:// navigation security control. By default, CDP clients cannot navigate to `file://` URLs (prevents local file read attacks). Enable only when local HTML testing is required.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
`pub async fn start_with_host_and_security(
    port: u16,
    host: &str,
    proxy: Option<String>,
    stealth: bool,
    user_agent: Option<String>,
    allow_file_access: bool,
    storage_dir: Option<std::path::PathBuf>,
) -> anyhow::Result<()>`

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| port | u16 | Yes | — | TCP port to listen on |
| host | &str | Yes | — | Host to bind to |
| proxy | Option<String> | No | None | HTTP/SOCKS5 proxy URL |
| stealth | bool | No | false | Enable anti-detection mode |
| user_agent | Option<String> | No | Chrome default | Custom User-Agent string |
| allow_file_access | bool | No | false | Allow `file://` navigation via CDP |
| storage_dir | Option<PathBuf> | No | None | Directory for persistent storage |

### Returns
`anyhow::Result<()>`

### Example
```rust
// Allow local file access for testing
obscura_cdp::start_with_host_and_security(
    9222,
    "127.0.0.1",
    None,
    false,
    None,
    true, // Allow file:// URLs
    None,
).await?;
```
```

--------------------------------

### Attach to Browser Target

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/endpoints.md

Use Target.attachToBrowserTarget to get a session ID for executing browser-level commands.

```json
{
  "sessionId": "browser-session"
}
```

--------------------------------

### Checking Obscura Version via CLI

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/modules.md

Command to display the installed Obscura version from the command line.

```bash
obscura --version
```

--------------------------------

### Network.getCookies Response Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/endpoints.md

This JSON structure represents the response when retrieving all cookies using the Network.getCookies method.

```json
{
  "cookies": [
    {
      "name": "sessionId",
      "value": "abc123",
      "domain": "example.com",
      "path": "/",
      "secure": true,
      "httpOnly": false,
      "sameSite": "Lax",
      "expires": 1735689600
    }
  ]
}
```

--------------------------------

### Configure HTTP Proxy with Authentication

Source: https://github.com/h4ckf0r0day/obscura/blob/main/docs/Configure-stealth-and-proxies.md

Provide authentication credentials (username and password) directly in the --proxy flag for HTTP proxies that require them.

```bash
obscura fetch https://example.com --proxy http://user:pass@proxy.example.com:8080
```

--------------------------------

### Fetch with Persistent Storage (CLI)

Source: https://github.com/h4ckf0r0day/obscura/wiki/Persist-cookies-and-storage

Use the --storage-dir flag with the 'fetch' command to save cookies and localStorage to disk, allowing them to persist across multiple runs.

```bash
obscura fetch https://example.com --storage-dir ./obscura-data
```

```bash
obscura fetch https://example.com --storage-dir ./obscura-data
```

--------------------------------

### Get DOM Tree Reference

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/page.md

Returns a reference to the DOM tree if available. Useful for querying elements.

```rust
pub fn dom(&self) -> Option<&DomTree>
```

```rust
if let Some(dom) = page.dom() {
    let all_links = dom.query_selector_all("a").unwrap_or_default();
}
```

--------------------------------

### Serve with Persistent Storage (Server)

Source: https://github.com/h4ckf0r0day/obscura/wiki/Persist-cookies-and-storage

Start the Obscura server with the --storage-dir flag to enable persistence of CDP session data. Multiple server instances can use different directories for isolated profiles.

```bash
obscura serve --storage-dir ./obscura-data
```

--------------------------------

### Download and Run Obscura (Linux ARM64)

Source: https://github.com/h4ckf0r0day/obscura/blob/main/README.md

Download the Obscura binary for Linux ARM64 (aarch64) and extract it.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-linux.tar.gz
tar xzf obscura-aarch64-linux.tar.gz
```

--------------------------------

### Download and Run Obscura (Linux x86_64)

Source: https://github.com/h4ckf0r0day/obscura/blob/main/README.md

Download the Obscura binary for Linux x86_64, extract it, and then use it to fetch a webpage and evaluate a JavaScript expression.

```bash
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura fetch https://example.com --eval "document.title"
```

--------------------------------

### browser_fill Tool Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Set the value of an input field by its CSS selector. This simulates input and change events.

```json
Tool: browser_fill
Input: {"selector": "input[name=email]", "value": "user@example.com"}
Output: { "success": true }
```

--------------------------------

### BrowserContext::new()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/browser-context.md

Creates a basic browser context with default settings. Requires a unique identifier for the context.

```APIDOC
## BrowserContext::new()

### Description
Creates a basic browser context with default settings.

### Method
Rust function call

### Parameters
#### Path Parameters
- **id** (String) - Required - Unique identifier for this context

### Returns
- **BrowserContext**

### Example
```rust
use obscura_browser::BrowserContext;

let context = BrowserContext::new("ctx-1".to_string());
```
```

--------------------------------

### Create Basic BrowserContext

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/browser-context.md

Use BrowserContext::new() to create a basic browser context with a unique identifier and default settings.

```rust
use obscura_browser::BrowserContext;

let context = BrowserContext::new("ctx-1".to_string());
```

--------------------------------

### BrowserContext::with_full_options()

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/browser-context.md

Creates a browser context with proxy, stealth mode, and a custom user-agent string. All optional parameters can be configured.

```APIDOC
## BrowserContext::with_full_options()

### Description
Creates a context with proxy, stealth, and custom user-agent options.

### Method
Rust function call

### Parameters
#### Path Parameters
- **id** (String) - Required - Unique identifier for this context
- **proxy_url** (Option<String>) - Optional - HTTP/SOCKS5 proxy URL
- **stealth** (bool) - Optional - Enable anti-detection mode
- **user_agent** (Option<String>) - Optional - Custom User-Agent string

### Returns
- **BrowserContext**

### Example
```rust
let context = BrowserContext::with_full_options(
    "ctx-1".to_string(),
    None,
    false,
    Some("Mozilla/5.0 (Custom) AppleWebKit/537.36".to_string()),
);
```
```

--------------------------------

### Get Node Outer HTML

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/endpoints.md

Retrieves the outer HTML of a specific DOM node using its node ID.

```json
{ "outerHTML": "<div id=\"main\">Content</div>" }
```

--------------------------------

### Basic Browser Interaction with Obscura API

Source: https://github.com/h4ckf0r0day/obscura/blob/main/crates/obscura/README.md

Demonstrates initializing the Obscura browser with stealth mode and a storage directory, navigating to a URL, waiting for a selector, and extracting element text and attributes.

```rust
use obscura::Browser;
use std::time::Duration;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::builder()
        .stealth(true)
        .storage_dir("/tmp/cookies")
        .build()?;

    let mut page = browser.new_page().await?;
    page.goto("https://example.com").await?;

    let el = page.wait_for_selector("a", Duration::from_secs(5)).await?;
    println!("{} -> {:?}", el.text(), el.attribute("href"));

    Ok(())
}
```

--------------------------------

### Get All Target Information

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/endpoints.md

Use Target.getTargets to retrieve a list of all currently open pages or targets within the browser.

```json
{
  "targetInfos": [
    {
      "targetId": "page-id",
      "type": "page",
      "title": "Page Title",
      "url": "https://example.com",
      "attached": true,
      "browserContextId": "ctx-1"
    }
  ]
}
```

--------------------------------

### Get Current URL

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/page.md

Returns the current page URL as a string. Returns 'about:blank' if the page has not been navigated.

```rust
pub fn url_string(&self) -> String
```

--------------------------------

### LP.getMarkdown Response Example

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/endpoints.md

This snippet shows the expected JSON response format when using LP.getMarkdown to convert DOM to Markdown.

```json
{
  "markdown": "# Page Title\n\nPage content in markdown format..."
}
```

--------------------------------

### Intercept Network Requests

Source: https://github.com/h4ckf0r0day/obscura/wiki/Use-with-Playwright

Intercept and modify or abort network requests. This example aborts image requests and allows others to continue.

```javascript
await page.route('**/*', route => {
  if (route.request().resourceType() === 'image') {
    route.abort();
  } else {
    route.continue();
  }
});
```

--------------------------------

### Configure BrowserContext with all options

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/configuration.md

Initializes a Rust BrowserContext with storage and network capabilities, specifying proxy, stealth mode, user agent, storage directory, and private network allowance.

```rust
use obscura_browser::BrowserContext;
use std::path::PathBuf;

// With all options
let context = BrowserContext::with_storage_and_network(
    "ctx-id",
    Some("http://proxy:8080".to_string()),  // proxy
    true,                                     // stealth
    Some("Custom-UA/1.0".to_string()),       // user_agent
    Some(PathBuf::from("/var/storage")),
    true,                                     // allow_private_network
);
```

--------------------------------

### Registering Rust Ops for JS Bridge

Source: https://github.com/h4ckf0r0day/obscura/wiki/Architecture-overview

Example of registering a Rust operation (`op_dom`) that can be called from JavaScript via the `Deno.core.ops` interface.

```javascript
Deno.core.ops.op_dom('insert_before', parentNid, refNid, newNid);
```

--------------------------------

### Create a New Page

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/page.md

Instantiates a new Page within a given BrowserContext. Requires a unique ID and the parent context.

```rust
use obscura_browser::{BrowserContext, Page};
use std::sync::Arc;

let context = Arc::new(BrowserContext::new("ctx-1".to_string()));
let page = Page::new("page-1".to_string(), context);
```

--------------------------------

### Handle Multi-Page Workflows with Browser Navigation

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/mcp-server.md

Demonstrates a multi-page workflow by navigating through pages, extracting data, and then using extracted information (like a next page URL) to navigate further.

```tool_code
1. browser_navigate: {"url": "page1"}
   → Extract data
2. browser_evaluate: {"expression": "document.querySelector('.next-page').href"}
   → Get next URL
3. browser_navigate: {"url": extracted_url}
   → Extract more data
```

--------------------------------

### Connect to CDP Server with Playwright

Source: https://github.com/h4ckf0r0day/obscura/blob/main/_autodocs/api-reference/cdp-server.md

Connects to a running CDP server using Playwright. This example demonstrates establishing a connection and navigating to a webpage.

```javascript
import { chromium } from 'playwright-core';

const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');

const page = await browser.newContext().then(ctx => ctx.newPage());
await page.goto('https://example.com');
console.log(await page.title());

await browser.close();
```