palyra-browserd is a specialized gRPC service responsible for managing headless Chromium instances. It provides a high-level API for browser automation, including session isolation, navigation, DOM interaction, and secure download handling. The daemon is designed to be consumed by the Palyra Orchestrator or the CLI to perform web-based tasks within a controlled sandbox.
Architecture & Service Implementation
The browser daemon is built on a gRPC interface defined inbrowser.proto and implemented via the BrowserServiceImpl struct. It manages a BrowserRuntimeState which tracks active sessions, profiles, and the lifecycle of the underlying Chromium engine.
Key Components
| Component | Role | Source |
|---|---|---|
BrowserServiceImpl | Implements gRPC handlers for session and tab management. | crates/palyra-browserd/src/transport/grpc/service.rs#9-11 |
BrowserRuntimeState | Central state container holding session maps and configuration. | crates/palyra-browserd/src/support/tests.rs#80-101 |
HeadlessBrowser | Wrapper around the headless_chrome crate for engine control. | crates/palyra-browserd/src/lib.rs#36-40 |
ChromiumSessionProxy | A SOCKS5 proxy spawned per session to intercept and validate traffic. | crates/palyra-browserd/src/engine/chromium.rs#71-75 |
Service Data Flow
The following diagram illustrates the lifecycle of a browser request from the gRPC layer down to the Chromium engine. Browser Request Flow Sources: crates/palyra-browserd/src/transport/grpc/service.rs#29-50, crates/palyra-browserd/src/transport/grpc/service.rs#15-27Chromium Engine Management
The daemon manages Chromium instances using theheadless_chrome crate. It supports different engine modes, including Simulated (for testing) and Native (using a local Chromium binary).
Session Isolation
Each session is strictly isolated:- Tempfile Storage: Every session utilizes a unique temporary directory for user data, ensuring no state leakage between runs unless persistence is explicitly enabled via a profile. crates/palyra-browserd/src/lib.rs#52-52
- SOCKS5 Proxying: To enforce network boundaries, each session can be routed through a
ChromiumSessionProxy. This proxy validates every outgoing connection request. crates/palyra-browserd/src/engine/chromium.rs#78-96 - Target Validation: Before navigation, URLs are passed through
validate_target_urlto prevent access to sensitive internal metadata services (e.g., AWS IMDS at169.254.169.254) or unauthorized private IP ranges. crates/palyra-browserd/src/support/tests.rs#1-17
Navigation & Retries
Chromium operations are wrapped inrun_chromium_blocking to ensure that long-running browser tasks do not block the asynchronous gRPC runtime. crates/palyra-browserd/src/engine/chromium.rs#60-68 The system also implements retry logic for common engine flakes, such as chromium_new_tab_error_is_retryable. crates/palyra-browserd/src/support/tests.rs#51-71
Download Handling & Sandbox
The daemon implements a multi-stage secure download pipeline. Downloads are not saved directly to the host’s standard download folder but are instead captured into aDownloadSandboxSession.
Download Lifecycle
- Trigger: A download is detected either via a
Clickaction on a download link or an explicitFetchrequest. crates/palyra-browserd/src/domain/downloads.rs#72-78 - Validation: The daemon checks the file extension and MIME type against an allowlist (e.g.,
txt,pdf,csv,zip). crates/palyra-browserd/src/lib.rs#153-162 - Quarantine: If a file fails validation but is still captured, it is placed in a
quarantinedirectory within the session’s temp root. crates/palyra-browserd/src/domain/downloads.rs#35-36 - Storage: Files are stored in a
TempDirwith a uniqueartifact_id. The total bytes used per session are tracked to prevent disk exhaustion. crates/palyra-browserd/src/domain/downloads.rs#20-25
Daemon-Side HTTP Handler
In addition to the gRPC interface,palyra-browserd exposes an internal HTTP server (usually on port 7143) used for health checks and by the palyrad console to proxy browser-related data.
Console Integration
The main Palyra daemon (palyrad) includes an Axum-based router that communicates with the browser daemon’s gRPC service to expose browser management to the Web Console. Key handlers include:
console_browser_profiles_list_handler: Lists available browser profiles for a principal. crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-9console_browser_profile_create_handler: Creates a new persistent browser profile. crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#34-38
Security Headers
The HTTP handler enforces authentication via anAUTHORIZATION_HEADER (Bearer token) and identifies the acting user via the PRINCIPAL_HEADER. crates/palyra-browserd/src/lib.rs#120-121
Configuration & Environment
The daemon’s behavior is heavily influenced by environment variables, allowing for flexible deployment in both desktop (Tauri) and headless (Server) environments.| Variable | Description | Default |
|---|---|---|
PALYRA_BROWSERD_STATE_DIR | Directory for persistent profiles and state. | OS-specific AppData |
PALYRA_BROWSERD_CHROMIUM_PATH | Path to the Chromium/Chrome executable. | Auto-detected |
PALYRA_BROWSERD_STATE_ENCRYPTION_KEY | 32-byte key for encrypting persisted state. | Required for persistence |
PALYRA_BROWSERD_ENGINE_MODE | native or simulated. | native |