palyra-browserd service is a specialized headless browser orchestration engine built on Chromium. It provides a gRPC interface for the Palyra daemon and CLI to perform web automation, content extraction, and session-based browsing with strong security boundaries and persistence.
System Overview
The service operates as a standalone gRPC server (browser.proto) that manages a pool of Chromium instances via the headless_chrome crate. It implements a session-based model where each session maintains its own isolated browser context, SOCKS5 proxy for network validation, and optional encrypted state persistence.
Code-to-Entity Mapping: Service Entry
| System Name | Code Entity | Description |
|---|---|---|
| gRPC Service | BrowserServiceImpl | Implements BrowserService trait for gRPC crates/palyra-browserd/src/transport/grpc/service.rs#9-11 |
| Runtime State | BrowserRuntimeState | Central coordinator for sessions, profiles, and configuration crates/palyra-browserd/src/support/tests.rs#80-82 |
| Engine | headless_chrome | Rust wrapper for the Chrome DevTools Protocol (CDP) crates/palyra-browserd/src/lib.rs#36-40 |
| State Store | PersistedStateStore | Handles encrypted filesystem persistence for profiles crates/palyra-browserd/src/support/tests.rs#12-16 |
Session Lifecycle and Orchestration
Sessions are the primary unit of isolation. When a session is created viacreate_session, the service initializes a ULID-based session ID, applies a SessionBudget for resource limits, and optionally restores state from the PersistedStateStore.
Session Creation Flow
Thecreate_session handler performs principal validation, profile resolution, and budget clamping before spawning a browser instance.
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#29-91, crates/palyra-browserd/src/transport/grpc/service.rs#107-165
Network Security and Target Validation
To prevent SSRF and unauthorized internal network access,palyra-browserd implements a multi-layered validation strategy for every URL navigation.
URL Validation Logic
Thevalidate_target_url_blocking function ensures that requested URLs conform to security policies before Chromium is allowed to navigate.
- DNS Resolution: Resolves the host to IP addresses crates/palyra-browserd/src/security/target_validation.rs#184-206.
- Netguard Check: Uses
palyra_common::netguardto identify private or local IP ranges (e.g., 127.0.0.1, 10.0.0.0/8) crates/palyra-browserd/src/security/target_validation.rs#10-17. - Policy Enforcement: Unless
allow_private_targetsis explicitly set, navigation to local/private IPs is blocked crates/palyra-browserd/src/security/target_validation.rs#195-203. - SOCKS5 Proxying: Each session can spawn a
ChromiumSessionProxythat enforces these rules at the socket level crates/palyra-browserd/src/engine/chromium.rs#71-97.
DNS Validation Cache
The service maintains aDnsValidationCache with LRU eviction to prevent repeated lookups and handle NXDOMAIN (negative) caching crates/palyra-browserd/src/security/target_validation.rs#27-42.
Sources: crates/palyra-browserd/src/security/target_validation.rs#10-17, crates/palyra-browserd/src/security/target_validation.rs#184-206, crates/palyra-browserd/src/engine/chromium.rs#71-97, crates/palyra-browserd/src/security/target_validation.rs#27-42
Download Management
Downloads are executed within aDownloadSandboxSession. This system prevents disk exhaustion and mitigates malware risks through extension and MIME-type filtering.
Download Sandbox Properties
- Isolation: Each session gets a unique temporary directory crates/palyra-browserd/src/domain/downloads.rs#28-32.
- Quarantine: Files with suspicious extensions or MIME types are moved to a
quarantinesubdirectory crates/palyra-browserd/src/domain/downloads.rs#35-36. - Limits: Enforces
DOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION(default 32MB) andDOWNLOAD_MAX_FILE_BYTES(default 8MB) crates/palyra-browserd/src/lib.rs#147-148. - Allowlist: Only specific extensions like
txt,pdf,json, andzipare permitted by default crates/palyra-browserd/src/lib.rs#153-162.
Entity Space: Download Handling
| Function | Role |
|---|---|
capture_download_artifact_for_click | Triggers download via element click and monitors result crates/palyra-browserd/src/domain/downloads.rs#72-78 |
store_generated_artifact | Persists raw bytes (e.g., PDF exports) into the sandbox crates/palyra-browserd/src/domain/downloads.rs#96-104 |
sanitize_download_file_name | Prevents path traversal in filenames crates/palyra-browserd/src/domain/downloads.rs#121 |
Persistence and State Store
ThePersistedStateStore manages long-lived browser profiles, including cookies, local storage, and session snapshots.
Security and Encryption
- Key Derivation: Uses
PALYRA_BROWSERD_STATE_ENCRYPTION_KEYto derive per-profile Data Encryption Keys (DEKs) crates/palyra-browserd/src/lib.rs#123-135. - Algorithm: Uses ChaCha20-Poly1305 for AEAD (Authenticated Encryption with Associated Data) crates/palyra-browserd/src/lib.rs#46-47.
- Integrity: Snapshots are validated using SHA-256 hashes with a versioned namespace (
palyra.browser.profile.record.v2) crates/palyra-browserd/src/lib.rs#145.
Data Layout
State is stored in the directory defined byPALYRA_BROWSERD_STATE_DIR crates/palyra-browserd/src/lib.rs#122.
profiles.enc: Encrypted registry of all profiles for a principal crates/palyra-browserd/src/lib.rs#138.[profile_id].pbs: Individual encrypted session snapshots.
CLI Integration
The Palyra CLI provides a comprehensive suite of commands to manage the browser service lifecycle and perform interactive automation.Browser Service Management
The CLI can supervise thepalyra-browserd binary, handling background startup and health monitoring.
| CLI Command | Code Implementation | Action |
|---|---|---|
palyra browser start | run_browser_start | Spawns palyra-browserd as a detached process crates/palyra-cli/src/commands/browser.rs#170-172 |
palyra browser status | run_browser_status | Checks gRPC and HTTP health endpoints crates/palyra-cli/src/commands/browser.rs#167-169 |
palyra browser open | run_browser_open | Creates a session and navigates to a URL crates/palyra-cli/src/commands/browser.rs#174-195 |
Interactive Commands
Commands likeclick, type, and snapshot map directly to browser.proto gRPC calls. For example, palyra browser click --selector ".btn" invokes the gRPC Click method on the running service crates/palyra-cli/src/commands/browser.rs#219-227.
Sources: crates/palyra-cli/src/commands/browser.rs#167-227, crates/palyra-cli/src/args/browser.rs#4-28