> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Automation (palyra-browserd)

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-browserd/src/app/bootstrap.rs
  * crates/palyra-browserd/src/app/config.rs
  * crates/palyra-browserd/src/app/mod.rs
  * crates/palyra-browserd/src/bin/palyra-browserd.rs
  * crates/palyra-browserd/src/domain/actions.rs
  * crates/palyra-browserd/src/domain/downloads.rs
  * crates/palyra-browserd/src/domain/mod.rs
  * crates/palyra-browserd/src/domain/session.rs
  * crates/palyra-browserd/src/engine/chromium.rs
  * crates/palyra-browserd/src/engine/mod.rs
  * crates/palyra-browserd/src/lib.rs
  * crates/palyra-browserd/src/persistence/mod.rs
  * crates/palyra-browserd/src/persistence/profile\_registry.rs
  * crates/palyra-browserd/src/persistence/session\_state.rs
  * crates/palyra-browserd/src/security/target\_validation.rs
  * crates/palyra-browserd/src/support/mod.rs
  * crates/palyra-browserd/src/support/tests.rs
  * crates/palyra-browserd/src/transport/grpc/service.rs
  * crates/palyra-cli/src/args/browser.rs
  * crates/palyra-cli/src/commands/browser.rs
  * crates/palyra-cli/tests/browser\_setup\_cli.rs
  * crates/palyra-cli/tests/help\_snapshots/browser-help.txt
  * crates/palyra-daemon/src/application/tool\_runtime/browser.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/browser.rs
</details>

The `palyra-browserd` daemon provides a secure, high-fidelity browser automation environment for Palyra agents. It abstracts complex browser interactions into a gRPC service, offering two distinct execution modes: a high-fidelity **Chromium** engine and a lightweight **Simulated** engine.

## System Architecture

The browser subsystem consists of three layers: the **CLI/Console** (user-facing control), the **Daemon Tool Runtime** (agent-facing broker), and the **Browser Daemon** (the execution engine).

### Data Flow: Agent to Browser

1. An agent proposes a `palyra.browser.*` tool call.
2. The `palyra-daemon` validates the request and brokers it via `execute_browser_tool` [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#11](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#11).
3. The daemon calls the `BrowserService` gRPC interface on `palyra-browserd` [crates/palyra-browserd/src/transport/grpc/service.rs#1](http://crates/palyra-browserd/src/transport/grpc/service.rs#1).
4. `palyra-browserd` executes the action in the requested engine (Chromium or Simulated).
5. Results are redacted, budgeted, and returned through the chain.

### Code Entity Map: Browser Service

The following diagram maps the gRPC service implementation to its underlying domain and engine entities.

```mermaid theme={null}
graph TD
    subgraph "Transport Layer (gRPC)"
        BSI["BrowserServiceImpl [crates/palyra-browserd/src/transport/grpc/service.rs:55]"]
    end

    subgraph "Domain Layer (State & Logic)"
        BRS["BrowserRuntimeState [crates/palyra-browserd/src/app/mod.rs]"]
        BSR["BrowserSessionRecord [crates/palyra-browserd/src/domain/session.rs]"]
        DSS["DownloadSandboxSession [crates/palyra-browserd/src/domain/downloads.rs:44]"]
    end

    subgraph "Engine Layer"
        CE["Chromium Engine [crates/palyra-browserd/src/engine/chromium.rs]"]
        SE["Simulated Engine [crates/palyra-browserd/src/engine/mod.rs]"]
    end

    BSI --> BRS
    BRS --> BSR
    BRS --> DSS
    BSR --> CE
    BSR --> SE
```

Sources: [crates/palyra-browserd/src/transport/grpc/service.rs#53-57](http://crates/palyra-browserd/src/transport/grpc/service.rs#53-57), [crates/palyra-browserd/src/domain/downloads.rs#44-50](http://crates/palyra-browserd/src/domain/downloads.rs#44-50), [crates/palyra-browserd/src/engine/chromium.rs#1-6](http://crates/palyra-browserd/src/engine/chromium.rs#1-6)

***

## Engine Modes

`palyra-browserd` supports two engines to balance resource usage and fidelity.

| Feature            | Chromium Engine               | Simulated Engine              |
| :----------------- | :---------------------------- | :---------------------------- |
| **Backend**        | Headless Chrome via CDP       | `reqwest` HTTP Client         |
| **JS Execution**   | Full (V8)                     | None (Static HTML)            |
| **Isolation**      | Process-per-session           | Shared async runtime          |
| **Best For**       | SPAs, Complex UI, Interaction | Fast scraping, Static content |
| **Capability Tag** | `javascript_execution: true`  | `javascript_execution: false` |

The `BrowserRuntimeCapabilities` struct is attached to every tool outcome to ensure agents do not mistake static HTML for a functional JS application [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#113-121](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#113-121).

Sources: [crates/palyra-browserd/src/engine/chromium.rs#1-6](http://crates/palyra-browserd/src/engine/chromium.rs#1-6), [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#108-121](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#108-121)

***

## Security and SSRF Protection

Browser automation is a high-risk vector for Server-Side Request Forgery (SSRF). `palyra-browserd` implements several layers of defense.

### DNS Pinning and Validation

To prevent DNS rebinding attacks, `palyra-browserd` resolves hostnames and validates them against a private/local IP policy *before* the browser or HTTP client initiates a connection [crates/palyra-browserd/src/security/target\_validation.rs#3-7](http://crates/palyra-browserd/src/security/target_validation.rs#3-7).

* **ResolvedHostAddresses**: Classifies IPs as public or private [crates/palyra-browserd/src/security/target\_validation.rs#13-16](http://crates/palyra-browserd/src/security/target_validation.rs#13-16).
* **DnsValidationCache**: A bounded NXDOMAIN-only cache to prevent resolution flooding [crates/palyra-browserd/src/security/target\_validation.rs#51-56](http://crates/palyra-browserd/src/security/target_validation.rs#51-56).
* **Pinning**: Validated IP addresses are passed directly to the transport layer to bypass secondary OS resolution.

### Navigation Guards

The `navigate_with_guards` function enforces policies on every navigation and redirect [crates/palyra-browserd/src/support/tests.rs#9](http://crates/palyra-browserd/src/support/tests.rs#9).

* **Relay Protection**: Requests originating from the browser extension (Relay) are strictly forbidden from accessing private targets [crates/palyra-browserd/src/transport/grpc/service.rs#12-18](http://crates/palyra-browserd/src/transport/grpc/service.rs#12-18).
* **SSRF Guard**: Blocks `127.0.0.1`, `169.254.169.254`, and other internal ranges unless explicitly permitted for `local_desktop` modes [crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#27-34](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#27-34).

Sources: [crates/palyra-browserd/src/security/target\_validation.rs#1-35](http://crates/palyra-browserd/src/security/target_validation.rs#1-35), [crates/palyra-browserd/src/transport/grpc/service.rs#12-18](http://crates/palyra-browserd/src/transport/grpc/service.rs#12-18), [crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#27-34](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#27-34)

***

## Session and Profile Management

### BrowserProfileRecord

Profiles provide durable storage for cookies, localStorage, and session state.

* **Persistence**: Profiles are stored as encrypted blobs using ChaCha20-Poly1305 [crates/palyra-browserd/src/app/config.rs#59-63](http://crates/palyra-browserd/src/app/config.rs#59-63).
* **Isolation**: Each profile is scoped to a `principal` (e.g., a specific user or agent) [crates/palyra-browserd/src/persistence/profile\_registry.rs#74](http://crates/palyra-browserd/src/persistence/profile_registry.rs#74).

### BrowserSessionRecord

A session represents a live instance of an engine.

* **Lifecycle**: Managed by `BrowserRuntimeState`. Sessions expire after `DEFAULT_SESSION_IDLE_TTL_MS` (10 minutes) [crates/palyra-browserd/src/app/config.rs#10](http://crates/palyra-browserd/src/app/config.rs#10).
* **Resource Limits**: Caps are enforced for tabs per session (default 32) and actions per window [crates/palyra-browserd/src/app/config.rs#20-31](http://crates/palyra-browserd/src/app/config.rs#20-31).

Sources: [crates/palyra-browserd/src/app/config.rs#10-31](http://crates/palyra-browserd/src/app/config.rs#10-31), [crates/palyra-browserd/src/app/config.rs#59-63](http://crates/palyra-browserd/src/app/config.rs#59-63)

***

## Diagnostics and Artifacts

### Script Injection

For Chromium sessions, `palyra-browserd` injects the `CHROMIUM_PAGE_DIAGNOSTICS_SCRIPT` into every page [crates/palyra-browserd/src/engine/chromium.rs#183](http://crates/palyra-browserd/src/engine/chromium.rs#183). This hook:

1. Wraps `console.log`, `fetch`, and `XMLHttpRequest`.
2. Buffers entries in a global `window.__palyraDiagnostics` object [crates/palyra-browserd/src/engine/chromium.rs#185](http://crates/palyra-browserd/src/engine/chromium.rs#185).
3. Allows the daemon to "drain" logs even if the page crashes or navigates.

### Download Quarantine

Captured downloads are managed by the `DownloadSandboxSession` [crates/palyra-browserd/src/domain/downloads.rs#44](http://crates/palyra-browserd/src/domain/downloads.rs#44).

* **Allowlist**: Files with safe extensions (e.g., `.pdf`, `.png`, `.json`) are stored in the `allowlist` directory [crates/palyra-browserd/src/app/config.rs#88-95](http://crates/palyra-browserd/src/app/config.rs#88-95).
* **Quarantine**: Executables or unknown MIME types are moved to `quarantine`. Their metadata is visible, but content retrieval is blocked [crates/palyra-browserd/src/domain/downloads.rs#132-137](http://crates/palyra-browserd/src/domain/downloads.rs#132-137).

### Redaction and Budgeting

All data returned to the agent is sanitized:

* **URL Redaction**: Query parameters and sensitive tokens are stripped [crates/palyra-browserd/src/support/mod.rs#90](http://crates/palyra-browserd/src/support/mod.rs#90).
* **Byte Budgeting**: Snapshots are truncated to prevent LLM context overflow [crates/palyra-browserd/src/support/mod.rs#19-23](http://crates/palyra-browserd/src/support/mod.rs#19-23).

Sources: [crates/palyra-browserd/src/engine/chromium.rs#183-222](http://crates/palyra-browserd/src/engine/chromium.rs#183-222), [crates/palyra-browserd/src/domain/downloads.rs#44-50](http://crates/palyra-browserd/src/domain/downloads.rs#44-50), [crates/palyra-browserd/src/domain/downloads.rs#132-137](http://crates/palyra-browserd/src/domain/downloads.rs#132-137), [crates/palyra-browserd/src/app/config.rs#88-95](http://crates/palyra-browserd/src/app/config.rs#88-95)

***

## Daemon-Side Tool Runtime

The `palyra-daemon` implements the `palyra.browser.*` tool family by proxying to `browserd`.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant TR["ToolRuntime [crates/palyra-daemon]"]
    participant BD["browserd [crates/palyra-browserd]"]
    participant Chrome["Chromium Process"]

    Agent->>TR: Proposal: palyra.browser.click(selector="#login")
    TR->>TR: Validate input size < MAX_BROWSER_TOOL_INPUT_BYTES
    TR->>BD: gRPC: ClickRequest(session_id, selector)
    BD->>Chrome: CDP: Runtime.evaluate(clickScript)
    Chrome-->>BD: Success
    BD->>BD: Record BrowserActionLogEntry
    BD-->>TR: ClickResponse(success=true)
    TR->>TR: Redact result (redact_text_for_export)
    TR-->>Agent: ToolExecutionOutcome
```

Sources: [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#11-65](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#11-65), [crates/palyra-browserd/src/engine/chromium.rs#1-6](http://crates/palyra-browserd/src/engine/chromium.rs#1-6)

### Key Functions

* `execute_browser_tool`: Main entry point for tool dispatch [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#11](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#11).
* `redact_text_for_export`: Ensures sensitive page content (like session tokens in the DOM) doesn't leak into the agent's memory [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#31](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#31).
* `BrowserRuntimeCapabilities::from_health`: Annotates tool results with engine metadata [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#126](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#126).

Sources: [crates/palyra-daemon/src/application/tool\_runtime/browser.rs#11-126](http://crates/palyra-daemon/src/application/tool_runtime/browser.rs#11-126)