palyra-browserd component is a specialized service responsible for high-fidelity browser automation and state management within the Palyra ecosystem. It integrates with Chromium via the headless_chrome crate to provide a programmable interface for agents and users to interact with the web while maintaining strict security boundaries and session persistence.
System Overview
The browser daemon operates as a standalone process that exposes a gRPC interface for control and an HTTP interface for health and relay operations. It manages a pool of browser sessions, each potentially backed by a persistent profile and protected by domain-level allowlists.Key Responsibilities
- Engine Integration: Managing the lifecycle of Chromium processes and tabs using
headless_chromecrates/palyra-browserd/src/lib.rs#39-43. - Session Management: Tracking active sessions, enforcing idle TTLs, and managing per-session budgets crates/palyra-browserd/src/transport/grpc/service.rs#93-161.
- Action Execution: Performing high-level actions like
Click,Type,Navigate, andSnapshotcrates/palyra-browserd/src/engine/chromium.rs#5-46. - Security & Validation: Enforcing non-loopback bind authentication and validating target URLs to prevent SSRF and unauthorized access crates/palyra-browserd/src/support/tests.rs#2-8.
- Persistence: Encrypting and storing browser profile state (cookies, local storage) to allow sessions to resume across daemon restarts crates/palyra-browserd/src/app/config.rs#52-61.
Implementation & Data Flow
The daemon is initialized via therun function in the bootstrap module crates/palyra-browserd/src/lib.rs#12-12. It sets up a BrowserRuntimeState which serves as the central coordination point for all shared resources.
Code Entity Space Mapping
The following diagram illustrates how natural language concepts map to specific Rust structs and services within thepalyra-browserd crate.
Entity Relationship Diagram
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#9-11, crates/palyra-browserd/src/support/tests.rs#8-12, crates/palyra-browserd/src/engine/chromium.rs#71-75.
Session Lifecycle
Sessions are created via thecreate_session gRPC call. This process involves resolving a profile, checking for existing persisted state, and initializing a new HeadlessBrowser instance or tab.
- Authorization: The request is validated using the
PRINCIPAL_HEADERand an optional auth token crates/palyra-browserd/src/transport/grpc/service.rs#33-38. - Profile Resolution: If a
profile_idis provided, the daemon loads the profile metadata and state encryption keys crates/palyra-browserd/src/transport/grpc/service.rs#42-48. - Persistence Loading: If persistence is enabled, a
PersistedSessionSnapshotis loaded from thePersistedStateStorecrates/palyra-browserd/src/transport/grpc/service.rs#75-91. - Budgeting: A
SessionBudgetis applied, defining limits for navigation timeouts, screenshot sizes, and action rates crates/palyra-browserd/src/transport/grpc/service.rs#107-161.
Action Flow: Navigation & Interaction
When an action likeNavigate or Click is requested, the daemon executes a blocking task on the engine.
Action Execution Sequence
Sources: crates/palyra-cli/src/commands/browser.rs#201-218, crates/palyra-browserd/src/transport/grpc/service.rs#29-32, crates/palyra-browserd/src/support/tests.rs#2-8.
Download Handling & Sandboxing
The daemon provides a managed download system to prevent malicious files from reaching the host filesystem directly.- DownloadSandboxSession: Every session has a dedicated temporary directory for downloads crates/palyra-browserd/src/domain/downloads.rs#20-25.
- Quarantine: Files are analyzed against an allowlist of extensions (e.g.,
txt,pdf,zip) and MIME types. Files failing these checks are moved to aquarantinesubdirectory crates/palyra-browserd/src/domain/downloads.rs#147-152. - Quota Enforcement: Total download size per session is capped by
DOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION(default 32MB) crates/palyra-browserd/src/app/config.rs#68-68.
Security Implementation
Target Validation
The daemon enforces strict URL validation to prevent SSRF (Server-Side Request Forgery). Thevalidate_target_url function checks if the requested URL is allowed based on the session’s action_allowed_domains and global settings like allow_private_targets crates/palyra-browserd/src/support/tests.rs#8-8.
State Encryption
Browser profiles are persisted using AES-GCM (ChaCha20-Poly1305) encryption.- Key Derivation: Keys are derived using a master
PALYRA_BROWSERD_STATE_ENCRYPTION_KEYand profile-specific salts crates/palyra-browserd/src/app/config.rs#44-56. - Storage: Encrypted blobs are stored in the state directory defined by
PALYRA_BROWSERD_STATE_DIRcrates/palyra-browserd/src/app/config.rs#43-43.
Configuration Defaults
| Parameter | Default Value | Description |
|---|---|---|
grpc_port | 7543 | gRPC service port crates/palyra-browserd/src/app/config.rs#3-3 |
max_sessions | 128 | Max concurrent browser sessions crates/palyra-browserd/src/app/config.rs#5-5 |
idle_ttl | 10 minutes | Session timeout after inactivity crates/palyra-browserd/src/app/config.rs#4-4 |
max_screenshot_bytes | 256 KB | Max size for captured screenshots crates/palyra-browserd/src/app/config.rs#8-8 |
max_tabs_per_session | 32 | Limit on tabs per browser instance crates/palyra-browserd/src/app/config.rs#25-25 |
CLI Integration
The Palyra CLI provides a comprehensive command set for interacting withpalyra-browserd, including lifecycle management (start, stop, status) and session interaction (open, click, type, snapshot) crates/palyra-cli/src/args/browser.rs#4-175.
Sources: crates/palyra-browserd/src/app/config.rs#1-100, crates/palyra-browserd/src/domain/downloads.rs#1-173, crates/palyra-browserd/src/transport/grpc/service.rs#1-161, crates/palyra-cli/src/commands/browser.rs#1-240.