palyra-browserd) is a specialized daemon responsible for high-fidelity browser automation and web content extraction. It acts as a secure wrapper around the Chromium engine, providing a gRPC interface for the Palyra ecosystem to perform actions like DOM manipulation, screenshot capture, and session-persistent web browsing.
System Overview
palyra-browserd is designed to run either as a local sidecar to the main daemon or as a remote service. It leverages the headless_chrome crate to control Chromium via the Chrome DevTools Protocol (CDP) crates/palyra-browserd/src/lib.rs#39-43.
Component Interaction
The following diagram illustrates how the Browser Service integrates with the broader Palyra architecture: Browser Service Context Diagram Sources: crates/palyra-browserd/src/transport/grpc/service.rs#9-11, crates/palyra-cli/src/commands/browser.rs#25-35, crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-15.Key Features
1. gRPC Service Interface
The service implements theBrowserService trait defined in palyra.browser.v1 crates/palyra-browserd/src/transport/grpc/service.rs#14-15. It handles requests for:
- Session Management: Creating and destroying isolated browser sessions with specific idle TTLs and resource budgets crates/palyra-browserd/src/transport/grpc/service.rs#29-107.
- Navigation & Interaction: Navigating to URLs, clicking elements, and typing text crates/palyra-cli/src/args/browser.rs#64-125.
- Observation: Capturing screenshots, DOM snapshots, and accessibility trees crates/palyra-cli/src/args/browser.rs#159-185.
2. Browser Profiles & Persistence
The service supports namedBrowserProfileRecord entities that store cookies and local storage. State is persisted using an encrypted PersistedStateStore crates/palyra-browserd/src/support/tests.rs#9-12.
- Encryption: State blobs are protected using ChaCha20-Poly1305 crates/palyra-browserd/src/lib.rs#49-51.
- Isolation: Private profiles ensure that sensitive session data is not persisted to disk crates/palyra-browserd/src/transport/grpc/service.rs#50-58.
3. Security & Domain Validation
The service enforces strict security boundaries:- Target Validation: URLs are validated against allowed domains and private network restrictions crates/palyra-browserd/src/support/tests.rs#8.
- Auth Tokens: gRPC calls require a Bearer token for authorization crates/palyra-browserd/src/support/tests.rs#40-44.
- Redaction: Sensitive query parameters (like OAuth
codeorstate) are redacted in logs crates/palyra-browserd/src/support/tests.rs#127-140.
4. Browser Extension (Relay Companion)
A Manifest V3 extension facilitates interaction between the user’s manual browsing and the daemon. It allows “relaying” page snapshots and selections directly to thepalyra-browserd loopback interface.
- For details, see Browser Extension (Relay Companion).
Internal Architecture
The daemon is structured into several core modules:engine: Manages the lifecycle of the Chromium process and tab allocation.domain: Contains the logic for browser actions (Click, Type, Scroll).persistence: Handles the encrypted SQLite storage for profiles.transport: Implements the gRPC server and health check endpoints.
Child Pages
- Browser Daemon Architecture: Deep dive into
headless_chromeintegration, resource budgeting, and the domain action state machine. - Browser Extension (Relay Companion): Technical details of the Manifest V3 extension, including the secure pairing flow and relay protocol.
palyra browser command group documentation in CLI Command Reference crates/palyra-cli/src/commands/browser.rs#160-200.