palyra-browserd daemon provides a managed, secure environment for browser automation using headless Chromium. It abstracts complex browser interactions into a gRPC service layer, handling session persistence, sandboxed downloads, and fine-grained action budgets.
Chromium Engine Integration
Palyra integrates with the Chromium engine via theheadless_chrome crate. The daemon manages the lifecycle of Chromium instances, ensuring they are launched with appropriate security flags and resource constraints.
Execution Modes
The engine supports two primary modes defined inBrowserEngineMode:
- Chromium: Launches a real headless Chromium process. The path is resolved via the
PALYRA_CHROMIUM_PATHenvironment variable or falls back to the system default crates/palyra-browserd/src/support/tests.rs#73-78. - Simulated: A mock engine used for testing and validation that does not require a Chromium binary crates/palyra-browserd/src/support/tests.rs#95-95.
Session Proxying
To enforce network security, each session can be associated with aChromiumSessionProxy. This is a SOCKS5 proxy spawned specifically for a session to intercept and validate outgoing requests, allowing or blocking private network targets based on session configuration crates/palyra-browserd/src/engine/chromium.rs#71-97.
Browser Engine Architecture
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#9-11, crates/palyra-browserd/src/engine/chromium.rs#71-97, crates/palyra-browserd/src/lib.rs#39-43
Session Lifecycle and Persistence
Sessions inpalyra-browserd are identified by ULIDs and governed by a SessionBudget that restricts lifetimes, memory usage, and action counts crates/palyra-browserd/src/transport/grpc/service.rs#93-161.
State Persistence
Whenpersistence_enabled is set, the daemon utilizes a PersistedStateStore to save and restore session snapshots.
- Encryption: State blobs are encrypted using
CHACHA20_POLY1305with a key derived fromPALYRA_BROWSERD_STATE_ENCRYPTION_KEYcrates/palyra-browserd/src/lib.rs#49-53, crates/palyra-browserd/src/support/tests.rs#2-4. - Snapshots: A
PersistedSessionSnapshotincludes cookies, localStorage, and session metadata. These are validated against theBrowserProfileRecordduring restoration to prevent cross-profile data leakage crates/palyra-browserd/src/support/tests.rs#7-12.
Download Handling
Downloads are isolated in aDownloadSandboxSession.
- Sandbox: Each session gets a unique temporary directory with
allowlistandquarantinesubdirectories crates/palyra-browserd/src/domain/downloads.rs#20-44. - Security: Files are checked against extension and MIME type allowlists. If they fail, they are moved to quarantine with a
quarantine_reasoncrates/palyra-browserd/src/domain/downloads.rs#105-118. - Quotas: The sandbox enforces
DOWNLOAD_MAX_TOTAL_BYTES_PER_SESSIONandMAX_DOWNLOAD_ARTIFACTS_PER_SESSION, automatically purging old artifacts when limits are reached crates/palyra-browserd/src/domain/downloads.rs#134-146.
gRPC Service Layer
TheBrowserServiceImpl implements the BrowserService gRPC contract, providing the primary interface for both the palyra-daemon and the CLI.
| Method | Purpose | Key Parameters |
|---|---|---|
CreateSession | Initializes a new browser context | principal, persistence_id, budget |
Navigate | Directs the active tab to a URL | url, allow_redirects, timeout_ms |
Click | Simulates a mouse click | selector, max_retries |
Type | Inputs text into an element | selector, text, clear_existing |
Snapshot | Captures DOM/Accessibility state | include_dom_snapshot, max_bytes |
CaptureScreenshot | Returns a PNG/JPEG of the page | max_bytes, format |
Browser Actions
The engine supports high-level actions that combine low-level Chrome DevTools Protocol (CDP) commands with Palyra-specific logic.Navigation and Observation
- Navigate: Includes guardrails for private target validation and redirect limits crates/palyra-browserd/src/engine/chromium.rs#38-46.
- Snapshot: Generates a
ChromiumObserveSnapshotcontaining the page body, title, and URL, truncated to fit the session budget crates/palyra-browserd/src/engine/chromium.rs#31-35, crates/palyra-browserd/src/engine/chromium.rs#48-58. - PDF: Generates a PDF of the current page using
PrintToPdfOptionscrates/palyra-browserd/src/engine/chromium.rs#2-2.
Interaction
- Select/Highlight: Used for identifying and visually marking elements for the operator or LLM.
- Console: Aggregates
BrowserPageDiagnostics, including warning and error counts from the browser’s internal console log crates/palyra-browserd/src/domain/actions.rs#21-45.