BrowserService is the primary interface for headless browser automation within the Palyra ecosystem. It is implemented as a gRPC service within palyra-browserd, providing a high-level abstraction over the Chrome DevTools Protocol (CDP) while enforcing strict security, resource constraints, and persistence policies.
Service Overview and Lifecycle
The browser daemon (palyra-browserd) manages a fleet of isolated browser sessions. Each session is bound to a specific principal (user or agent) and can optionally be associated with a BrowserProfile for persistent storage of cookies and local data.
Session Lifecycle Flow
The following diagram illustrates the lifecycle from session creation to termination, including profile resolution and state persistence. Diagram: Browser Session Lifecycle Sources:[crates/palyra-browserd/src/transport/grpc/service.rs#27-165](http://crates/palyra-browserd/src/transport/grpc/service.rs#27-165), [crates/palyra-browserd/src/lib.rs#83-92](http://crates/palyra-browserd/src/lib.rs#83-92)
gRPC API Methods
TheBrowserService defines a comprehensive suite of methods for tab and page interaction. All methods require a valid principal header and an optional authorization token.
Core Session Management
| Method | Description | Key Parameters |
|---|---|---|
CreateSession | Initializes a new Chromium instance or attaches to a profile. | principal, profile_id, budget, persistence_enabled |
CloseSession | Terminates the browser process and saves state if enabled. | session_id |
Health | Returns daemon uptime and active session counts. | v (protocol version) |
Navigation and Interaction
| Method | Description | Key Constraints |
|---|---|---|
Navigate | Navigates the active tab to a target URL. | Subject to validate_target_url (DNS/IP checks). |
Click | Simulates a mouse click on a CSS selector. | Max retries and timeout enforced by SessionBudget. |
Type | Inputs text into a form field. | max_type_input_bytes limit. |
Scroll | Scrolls the page to a selector or coordinates. | Enforces rate limits on UI actions. |
WaitFor | Blocks until a selector appears or text is present. | Limited by max_navigation_timeout_ms. |
Inspection and Data Extraction
| Method | Description | Behavior |
|---|---|---|
Screenshot | Captures a PNG/JPEG of the current viewport. | Clamped by max_screenshot_bytes. |
Observe | Returns a DOM snapshot, accessibility tree, and visible text. | Truncated by max_observe_snapshot_bytes. |
NetworkLog | Retrieves recent HTTP traffic for the session. | Limited to max_network_log_entries. |
[crates/palyra-browserd/src/transport/grpc/service.rs#12-25](http://crates/palyra-browserd/src/transport/grpc/service.rs#12-25), [crates/palyra-browserd/src/lib.rs#82-102](http://crates/palyra-browserd/src/lib.rs#82-102), [crates/palyra-cli/src/commands/browser.rs#210-245](http://crates/palyra-cli/src/commands/browser.rs#210-245)
SessionBudget and Resource Constraints
To prevent resource exhaustion and “runaway” automation, every session is governed by aSessionBudget. If not explicitly provided during CreateSession, the daemon applies system-wide defaults.
| Budget Key | Default Value | Description |
|---|---|---|
max_navigation_timeout_ms | 15,000 ms | Max time for a page load to complete. |
max_screenshot_bytes | 256 KB | Max size for image artifacts. |
max_actions_per_session | 256 | Hard limit on interaction calls per session. |
max_actions_per_window | 20 | Rate limiting window for UI interactions. |
max_observe_snapshot_bytes | 64 KB | Max size for DOM/Accessibility trees. |
[crates/palyra-browserd/src/lib.rs#85-100](http://crates/palyra-browserd/src/lib.rs#85-100), [crates/palyra-browserd/src/transport/grpc/service.rs#105-165](http://crates/palyra-browserd/src/transport/grpc/service.rs#105-165)
BrowserProfile Persistence
palyra-browserd supports persistent browser profiles, allowing sessions to maintain login states across restarts.
- Storage: Profiles are stored in the directory defined by
PALYRA_BROWSERD_STATE_DIR(defaulting to platform-specific AppData/Application Support). - Encryption: State snapshots are encrypted using ChaCha20-Poly1305. The key is derived from
PALYRA_BROWSERD_STATE_ENCRYPTION_KEY. - Integrity: Each
PersistedSessionSnapshotincludes a hash-chain and version metadata (PROFILE_RECORD_SCHEMA_VERSION) to prevent loading incompatible or tampered state.
[crates/palyra-browserd/src/support/tests.rs#2-16](http://crates/palyra-browserd/src/support/tests.rs#2-16), [crates/palyra-browserd/src/lib.rs#125-135](http://crates/palyra-browserd/src/lib.rs#125-135), [crates/palyra-browserd/src/transport/grpc/service.rs#73-89](http://crates/palyra-browserd/src/transport/grpc/service.rs#73-89)
Failure Handling and Diagnostics
The service implements automated diagnostic capture for failed interactions.Failure Screenshot Capture
When aClick, Type, or WaitFor action fails (e.g., selector not found), the service can automatically capture a screenshot of the browser state at the moment of failure. This is controlled by the capture_failure_screenshot flag in the RPC request.
Remote IP Guard
To prevent SSRF and unauthorized access to internal infrastructure, thenavigate_with_guards function validates every target URL. It uses record_chromium_remote_ip_incident to track and block attempts to access loopback or private network ranges unless allow_private_targets is explicitly enabled for the session.
Doctor Integration
Thepalyra doctor command performs deep inspections of the browser environment, including:
- Checking Chromium binary availability via
PALYRA_BROWSERD_CHROMIUM_PATH. - Validating the
profiles.encregistry integrity. - Verifying state encryption key availability.
[crates/palyra-browserd/src/support/tests.rs#5-8](http://crates/palyra-browserd/src/support/tests.rs#5-8), [crates/palyra-cli/src/commands/browser.rs#135-148](http://crates/palyra-cli/src/commands/browser.rs#135-148), [crates/palyra-cli/src/commands/doctor/recovery.rs#31-40](http://crates/palyra-cli/src/commands/doctor/recovery.rs#31-40)