palyra-browserd component is a specialized daemon responsible for managing headless Chromium instances. It provides a high-level gRPC interface for browser automation, session management, and secure web navigation. It is designed to run either as a background service managed by the Palyra CLI or as a sidecar in the Desktop application.
Core Architecture & Engine
The daemon is built around theheadless_chrome crate, which interfaces with Chromium via the DevTools Protocol (CDP) crates/palyra-browserd/Cargo.toml#17-17. It manages a pool of browser sessions, each isolated with its own temporary or persisted user data directory.
Browser Engine Modes
The daemon supports different execution modes defined inBrowserEngineMode crates/palyra-browserd/src/support/tests.rs#9-9:
- Chromium: Standard mode using a real Chromium/Chrome binary.
- Simulated: A mock engine used for unit testing the gRPC service layer without requiring a full browser environment crates/palyra-browserd/src/support/tests.rs#80-101.
Component Interaction Diagram
This diagram illustrates how theBrowserServiceImpl coordinates between the gRPC transport and the underlying engine.
Browser Daemon Internal Data Flow
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#9-11, crates/palyra-browserd/src/engine/chromium.rs#71-75, crates/palyra-browserd/src/domain/downloads.rs#20-25
gRPC Service Interface
TheBrowserService is the primary interface for palyrad and the CLI. It is defined in Protobuf and implemented by BrowserServiceImpl crates/palyra-browserd/src/transport/grpc/service.rs#14-14.
Key Service Methods
| Method | Description |
|---|---|
health | Returns uptime and active session counts crates/palyra-browserd/src/transport/grpc/service.rs#15-27. |
create_session | Initializes a new Chromium instance with specific SessionBudget and persistence_id crates/palyra-browserd/src/transport/grpc/service.rs#29-32. |
navigate | Directs the browser to a URL, subject to SSRF protection crates/palyra-browserd/src/engine/chromium.rs#38-46. |
click / type | Performs DOM interactions within the active tab crates/palyra-browserd/src/engine/chromium.rs#5-10. |
snapshot | Captures DOM, accessibility tree, and visible text crates/palyra-browserd/src/engine/chromium.rs#31-35. |
Session Lifecycle & Persistence
Sessions are identified by ULIDs crates/palyra-browserd/src/transport/grpc/service.rs#93-93. The lifecycle is governed byBrowserRuntimeState, which handles cleanup of idle sessions crates/palyra-browserd/src/lib.rs#119-119.
Persistence & Encryption
Ifpersistence_enabled is set, the daemon uses a PersistedStateStore to save session snapshots crates/palyra-browserd/src/transport/grpc/service.rs#75-91.
- Encryption: State blobs are encrypted using ChaCha20-Poly1305 crates/palyra-browserd/src/lib.rs#47-47.
- Key Derivation: Keys are derived from
PALYRA_BROWSERD_STATE_ENCRYPTION_KEYcrates/palyra-browserd/src/lib.rs#123-123. - Storage: Profiles and sessions are stored in the directory defined by
PALYRA_BROWSERD_STATE_DIRcrates/palyra-browserd/src/lib.rs#122-122.
Security & SSRF Protection
palyra-browserd implements multi-layered protection against Server-Side Request Forgery (SSRF) and unauthorized egress.
Target Validation
Before any navigation, the daemon validates the target URL usingvalidate_target_url_blocking crates/palyra-browserd/src/security/target_validation.rs#184-187.
- DNS Resolution: Resolves the host to IP addresses crates/palyra-browserd/src/security/target_validation.rs#201-201.
- Netguard Check: Checks if IPs are private or local (e.g.,
127.0.0.1,169.254.169.254) crates/palyra-browserd/src/security/target_validation.rs#14-15. - Policy Enforcement: Unless
allow_private_targetsis explicitly true, requests to local/private ranges are blocked crates/palyra-browserd/src/security/target_validation.rs#202-202.
SOCKS5 Proxy Egress
For granular control, the daemon can spawn aChromiumSessionProxy crates/palyra-browserd/src/engine/chromium.rs#71-75. This acts as a SOCKS5 proxy that intercepts all Chromium network requests, allowing the daemon to enforce allow_private_targets at the socket level crates/palyra-browserd/src/engine/chromium.rs#198-201.
Security Validation Logic
Sources: crates/palyra-browserd/src/security/target_validation.rs#184-206, crates/palyra-browserd/src/engine/chromium.rs#198-210
Download Management
Downloads are handled within aDownloadSandboxSession crates/palyra-browserd/src/domain/downloads.rs#20-25.
- Isolation: Each session gets a unique temporary directory crates/palyra-browserd/src/domain/downloads.rs#29-32.
- Quarantine: Files are initially placed in a
quarantinedirectory crates/palyra-browserd/src/domain/downloads.rs#36-36. - Validation: Files are checked against
DOWNLOAD_ALLOWED_EXTENSIONS(e.g.,.pdf,.csv,.json) andDOWNLOAD_ALLOWED_MIME_TYPEScrates/palyra-browserd/src/lib.rs#153-162. - Limits: Enforces
DOWNLOAD_MAX_FILE_BYTES(8MB) andDOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION(32MB) crates/palyra-browserd/src/lib.rs#147-148.
CLI Integration
The Palyra CLI manages thepalyra-browserd process lifecycle via the browser command group crates/palyra-cli/src/commands/browser.rs#160-166.
- Start/Stop: The CLI can spawn the daemon as a detached process and monitor its health via the
healthgRPC endpoint crates/palyra-cli/src/commands/browser.rs#170-173. - Metadata: The CLI tracks the running daemon’s PID and gRPC URL in a local
browser-service.jsonmetadata file crates/palyra-cli/src/commands/browser.rs#31-31.