palyra-browserd service is a specialized daemon providing headless Chromium automation via a gRPC interface. It manages the lifecycle of browser sessions, profiles, and tabs, while enforcing strict security boundaries through target validation and isolated network proxies.
System Architecture
The daemon is built on top of theheadless_chrome crate and provides a high-level abstraction for complex browser interactions like DOM observation, action retries, and state persistence.
Component Interaction Diagram
This diagram illustrates the relationship between the gRPC service, the runtime state, and the underlying browser engine. Title: Browser Daemon Internal 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/lib.rs#36-40Session Lifecycle & Management
TheBrowserRuntimeState acts as the central orchestrator for all active browser sessions crates/palyra-browserd/src/transport/grpc/service.rs#10-11.
- Creation: Sessions are created via
create_sessionwith specificSessionBudgetconstraints (timeouts, max screenshot bytes, etc.) crates/palyra-browserd/src/transport/grpc/service.rs#29-107. - Profiles: Sessions can be attached to a
BrowserProfileRecord. Ifpersistence_enabledis true, the daemon restores the session state (cookies, localStorage) from thePersistedStateStorecrates/palyra-browserd/src/transport/grpc/service.rs#51-91. - Idle TTL: The daemon automatically cleans up sessions that have been inactive longer than the
idle_ttl_mscrates/palyra-browserd/src/transport/grpc/service.rs#95-99. - Concurrency: The daemon enforces a
max_sessionslimit (default 128) to prevent resource exhaustion crates/palyra-browserd/src/lib.rs#84-84.
Session State Persistence
State is stored in an encrypted format usingCHACHA20_POLY1305 crates/palyra-browserd/src/lib.rs#47-47. The PersistedStateStore manages profiles.enc and individual profile data blobs crates/palyra-browserd/src/lib.rs#131-140.
Sources: crates/palyra-browserd/src/transport/grpc/service.rs#29-130, crates/palyra-browserd/src/lib.rs#131-145
Engine Integration & SOCKS5 Proxy
To ensure security and prevent Server-Side Request Forgery (SSRF), every browser session is isolated behind a per-session SOCKS5 proxy:ChromiumSessionProxy crates/palyra-browserd/src/engine/chromium.rs#71-75.
Security Flow: Target Validation
Title: Network Request Validation Pipeline Sources: crates/palyra-browserd/src/engine/chromium.rs#114-145, crates/palyra-browserd/src/security/target_validation.rs#184-206, crates/palyra-browserd/src/engine/chromium.rs#147-149 Key validation logic:- Private IP Guard: Blocks access to local network ranges (10.0.0.0/8, 127.0.0.1, etc.) unless
allow_private_targetsis explicitly enabled for the session crates/palyra-browserd/src/security/target_validation.rs#14-17. - DNS Caching: The
DnsValidationCachetracks NXDOMAIN results and resolution latency to optimize validation performance crates/palyra-browserd/src/security/target_validation.rs#27-42. - Redaction: URL query parameters like
codeorstate(OAuth) are automatically redacted in logs crates/palyra-browserd/src/support/tests.rs#128-140.
Download Management
Downloads are handled within aDownloadSandboxSession. Files are initially placed in a quarantine directory if they do not match the allowlisted extensions or MIME types crates/palyra-browserd/src/domain/downloads.rs#20-44.
- Limits: Enforces
DOWNLOAD_MAX_FILE_BYTES(8MB) andDOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION(32MB) crates/palyra-browserd/src/lib.rs#147-148. - Allowlist: Only specific extensions (txt, csv, json, pdf, zip, gz) are promoted out of quarantine crates/palyra-browserd/src/lib.rs#153-153.
- Cleanup: The sandbox uses a
VecDequeofDownloadArtifactRecordand pops the oldest artifacts whenMAX_DOWNLOAD_ARTIFACTS_PER_SESSIONis reached crates/palyra-browserd/src/domain/downloads.rs#141-146.
CLI Browser Commands
Thepalyra CLI provides a comprehensive suite of commands to interact with palyra-browserd.
| Command | Function | Key Code Entity |
|---|---|---|
palyra browser start | Spawns the daemon as a background process | run_browser_start |
palyra browser open | Creates a session and navigates to a URL | run_browser_open |
palyra browser click | Clicks a DOM element via CSS selector | run_browser_click |
palyra browser snapshot | Captures DOM, Accessibility Tree, and Text | run_browser_snapshot |
palyra browser trace | Exports session debug artifacts | BrowserCommand::Trace |
Implementation of run_browser_start
When starting the daemon, the CLI:
- Locates the
palyra-browserdbinary crates/palyra-cli/src/commands/browser.rs#74-74. - Configures stdout/stderr log redirection to
browserd.stdout.logcrates/palyra-cli/src/commands/browser.rs#32-33. - Writes a
browser-service.jsonmetadata file containing the PID and gRPC URL crates/palyra-cli/src/commands/browser.rs#71-80. - Polls the health endpoint until the service is ready crates/palyra-cli/src/commands/browser.rs#29-29.