palyra-browserd binary is a specialized microservice responsible for orchestrating headless Chromium instances. It provides a high-level gRPC interface (BrowserService) that abstracts complex browser interactions into atomic agent-friendly actions like clicking, typing, and observing page state. It is designed to run either as a sidecar to the main palyrad daemon or as a standalone service.
Service Architecture
The architecture is built around a centralBrowserRuntimeState which manages the lifecycle of multiple browser sessions, each potentially backed by a distinct Chromium process or tab.
Component Overview
| Component | Responsibility |
|---|---|
BrowserServiceImpl | Implements the gRPC service defined in browser.proto. Handles request authorization and dispatches to the runtime. |
BrowserRuntimeState | The “brain” of the service. Manages the session registry, configuration budgets, and the state store. |
HeadlessBrowser | Integration with the headless_chrome crate to control the underlying Chromium engine. |
PersistedStateStore | Handles encrypted storage of browser profiles and session snapshots to disk. |
ChromiumSessionProxy | A per-session SOCKS5 proxy used to enforce egress security and target validation. |
System Data Flow
The following diagram illustrates how a request from thepalyra-daemon (or CLI) flows through palyra-browserd to the Chromium engine.
Request Execution Flow
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#14-14, crates/palyra-browserd/src/engine/chromium.rs#71-75, crates/palyra-browserd/src/security/target_validation.rs#184-187
gRPC API (browser.proto)
The service communicates via Protobuf over gRPC, typically listening on port 7543.
Key RPC Methods
CreateSession: Initializes a new browser context. It can restore state from apersistence_idand apply aSessionBudgetto limit resource consumption. crates/palyra-browserd/src/transport/grpc/service.rs#29-32Navigate: Directs the active tab to a URL. Includesallow_private_targetsandmax_redirectsguards. crates/palyra-cli/src/args/browser.rs#65-77Observe: Returns a structured snapshot of the page, including the DOM, accessibility tree, and visible text, truncated to fitmax_observe_snapshot_bytes. crates/palyra-cli/src/args/browser.rs#159-175PerformAction: A unified entry point forClick,Type,Scroll, andWaitoperations. crates/palyra-cli/src/args/browser.rs#79-157
Session Lifecycle and Budgets
Sessions are identified by ULIDs and are governed by aSessionBudget. This budget prevents runaway agents from consuming excessive memory or performing too many actions.
| Budget Field | Default Value | Description |
|---|---|---|
max_navigation_timeout_ms | 15,000ms | Max time for a page load. |
max_screenshot_bytes | 256 KB | Cap on image data returned. |
max_actions_per_session | 256 | Total interactions allowed. |
max_tabs_per_session | 32 | Concurrent tabs per session. |
Chromium Integration and Security
palyra-browserd uses the headless_chrome crate but wraps it in several security layers to ensure agent safety.
Target Validation and Egress Control
Every network request made by the browser is intercepted via a local SOCKS5 proxy (ChromiumSessionProxy). This proxy performs “Target Validation” to prevent SSRF (Server-Side Request Forgery) and unauthorized access to local infrastructure.
validate_target_url: Checks if the destination IP is private/local (e.g.,127.0.0.1,192.168.x.x). Unlessallow_private_targetsis explicitly true, these are blocked. crates/palyra-browserd/src/security/target_validation.rs#184-193- DNS Caching: The system maintains a
DnsValidationCacheto prevent DNS rebinding attacks and improve performance. crates/palyra-browserd/src/security/target_validation.rs#27-32
Download Handling
Downloads are strictly sandboxed. When an agent triggers a download (e.g., viaClick), the file is captured into a DownloadSandboxSession.
- Quarantine: Files are initially placed in a
quarantinedirectory. - Validation: The service checks
DOWNLOAD_ALLOWED_EXTENSIONS(e.g.,.pdf,.csv,.json) andDOWNLOAD_ALLOWED_MIME_TYPES. crates/palyra-browserd/src/lib.rs#153-162 - Storage: If valid, the file is moved to an
allowlistdirectory within aTempDirunique to the session. crates/palyra-browserd/src/domain/downloads.rs#20-36
Implementation Detail: State Persistence
palyra-browserd supports persistent profiles, allowing agents to maintain login sessions across restarts.
State Persistence Architecture
State is encrypted using CHACHA20_POLY1305 with a key derived from PALYRA_BROWSERD_STATE_ENCRYPTION_KEY. The PersistedStateStore manages the profiles.enc registry and individual session blobs.
Sources: crates/palyra-browserd/src/lib.rs#123-133, crates/palyra-browserd/src/transport/grpc/service.rs#75-91, crates/palyra-browserd/src/support/tests.rs#3-7
CLI Interaction
Thepalyra-cli provides a comprehensive interface for managing browserd.
palyra browser start: Launches the daemon and waits for it to be healthy. crates/palyra-cli/src/commands/browser.rs#170-172palyra browser open --url <URL>: Creates a session and navigates in one step. crates/palyra-cli/src/commands/browser.rs#184-195palyra browser snapshot <SESSION_ID>: Captures the current state for inspection. crates/palyra-cli/src/args/browser.rs#159-175