Skip to main content
The browser automation service, palyra-browserd, is a specialized daemon responsible for managing headless Chromium instances. It provides a high-level gRPC interface for web navigation, DOM interaction, and session persistence, abstracting the complexity of the Chrome DevTools Protocol (CDP).

​
Service Overview and Lifecycle

The palyra-browserd binary operates as a standalone service, typically supervised by the main Palyra daemon or the Desktop Companion [crates/palyra-browserd/src/bin/palyra-browserd.rs#10-10](http://crates/palyra-browserd/src/bin/palyra-browserd.rs#10-10). It manages a pool of browser sessions, each associated with a specific principal and optional persistent profile.

​
Session Lifecycle

  1. Creation: A session is initialized via CreateSession [crates/palyra-browserd/src/transport/grpc/service.rs#29-32](http://crates/palyra-browserd/src/transport/grpc/service.rs#29-32). This involves resolving a BrowserProfileRecord and determining if state should be restored from the PersistedStateStore [crates/palyra-browserd/src/transport/grpc/service.rs#75-91](http://crates/palyra-browserd/src/transport/grpc/service.rs#75-91).
  2. Execution: Actions such as Navigate, Click, and Type are dispatched to the BrowserRuntimeState [crates/palyra-browserd/src/transport/grpc/service.rs#10-11](http://crates/palyra-browserd/src/transport/grpc/service.rs#10-11).
  3. Persistence: If enabled, the session state (cookies, localStorage) is encrypted and saved to disk upon session termination or periodic checkpoints [crates/palyra-browserd/src/transport/grpc/service.rs#75-80](http://crates/palyra-browserd/src/transport/grpc/service.rs#75-80).
  4. Cleanup: An internal loop monitors session idle times and total lifetimes, reaping sessions that exceed idle_ttl_ms or max_session_lifetime_ms [crates/palyra-browserd/src/lib.rs#83-86](http://crates/palyra-browserd/src/lib.rs#83-86).

​
System Architecture Diagram

This diagram maps the natural language concepts of browser management to the specific Rust entities in the codebase. “Browser Service Entity Mapping” Sources: [crates/palyra-browserd/src/transport/grpc/service.rs#9-11](http://crates/palyra-browserd/src/transport/grpc/service.rs#9-11), [crates/palyra-browserd/src/lib.rs#36-40](http://crates/palyra-browserd/src/lib.rs#36-40), [crates/palyra-browserd/src/support/tests.rs#9-12](http://crates/palyra-browserd/src/support/tests.rs#9-12)

​
gRPC Interface Definition

The service interface is defined in browser.proto and compiled into Rust stubs via tonic [crates/palyra-browserd/build.rs#14-17](http://crates/palyra-browserd/build.rs#14-17).

​
Key Service Methods

MethodDescriptionSource
CreateSessionInitializes a new Chromium instance or tab with specific budgets.[crates/palyra-browserd/src/transport/grpc/service.rs#29-32](http://crates/palyra-browserd/src/transport/grpc/service.rs#29-32)
NavigateDirects the active tab to a target URL with redirect validation.[crates/palyra-cli/src/commands/browser.rs#201-208](http://crates/palyra-cli/src/commands/browser.rs#201-208)
SnapshotCaptures DOM, accessibility tree, and visible text within byte limits.[crates/palyra-browserd/src/lib.rs#159-175](http://crates/palyra-browserd/src/lib.rs#159-175)
Click/TypePerforms low-level input simulation on DOM elements.[crates/palyra-cli/src/args/browser.rs#79-109](http://crates/palyra-cli/src/args/browser.rs#79-109)
ListProfilesEnumerates available persistent browser profiles for a principal.[crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-15](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-15)
Sources: [crates/palyra-browserd/src/transport/grpc/service.rs#1-32](http://crates/palyra-browserd/src/transport/grpc/service.rs#1-32), [crates/palyra-cli/src/args/browser.rs#4-227](http://crates/palyra-cli/src/args/browser.rs#4-227)

​
Security and Validation

The service implements multi-layered security to prevent SSRF and unauthorized access.

​
Target URL Validation

Before any navigation, the validate_target_url function checks the destination [crates/palyra-browserd/src/support/tests.rs#8-8](http://crates/palyra-browserd/src/support/tests.rs#8-8).
  • Private Targets: Navigation to loopback or private IP ranges is blocked unless allow_private_targets is explicitly set in the session request [crates/palyra-browserd/src/transport/grpc/service.rs#113-113](http://crates/palyra-browserd/src/transport/grpc/service.rs#113-113).
  • DNS Rebinding: The service employs a DnsValidationCache to track and validate resolved IPs against the original target hostname [crates/palyra-browserd/src/support/tests.rs#11-11](http://crates/palyra-browserd/src/support/tests.rs#11-11).

​
Data Flow: Navigation and Validation

“Navigation Request Flow” Sources: [crates/palyra-browserd/src/transport/grpc/service.rs#15-19](http://crates/palyra-browserd/src/transport/grpc/service.rs#15-19), [crates/palyra-browserd/src/support/tests.rs#8-8](http://crates/palyra-browserd/src/support/tests.rs#8-8), [crates/palyra-cli/src/commands/browser.rs#201-218](http://crates/palyra-cli/src/commands/browser.rs#201-218)

​
Download and Artifact Management

palyra-browserd manages downloads through a tiered directory structure:
  • Quarantine: Initial destination for all downloads [crates/palyra-browserd/src/lib.rs#151-151](http://crates/palyra-browserd/src/lib.rs#151-151).
  • Allowlist: Files that pass validation (extension and MIME type checks) are moved here [crates/palyra-browserd/src/lib.rs#150-150](http://crates/palyra-browserd/src/lib.rs#150-150).

​
Constraints

  • File Size: Individual downloads are capped at DOWNLOAD_MAX_FILE_BYTES (8MB) [crates/palyra-browserd/src/lib.rs#148-148](http://crates/palyra-browserd/src/lib.rs#148-148).
  • Total Session Budget: Sessions are limited to DOWNLOAD_MAX_TOTAL_BYTES_PER_SESSION (32MB) [crates/palyra-browserd/src/lib.rs#147-147](http://crates/palyra-browserd/src/lib.rs#147-147).
  • Allowed Types: Only specific extensions (e.g., txt, pdf, json) and MIME types are permitted [crates/palyra-browserd/src/lib.rs#153-162](http://crates/palyra-browserd/src/lib.rs#153-162).
Sources: [crates/palyra-browserd/src/lib.rs#147-162](http://crates/palyra-browserd/src/lib.rs#147-162)

​
Integration with Palyra Daemon

The main palyrad daemon interacts with the browser service through the BrowserHandler.

​
Console API Integration

The daemon’s Axum-based HTTP layer provides endpoints for the Web Dashboard to manage browser profiles and sessions:
  • Profile Management: Handlers like console_browser_profiles_list_handler proxy requests to the gRPC list_profiles method [crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-22](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-22).
  • Authentication: The daemon applies internal service authentication tokens to the gRPC metadata using apply_browser_service_auth [crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#20-20](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#20-20).
  • Event Recording: Browser actions initiated via the console are recorded in the system logs via record_browser_console_event [crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#70-82](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#70-82).
Sources: [crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#1-133](http://crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#1-133)