Skip to main content
The Palyra protocol is defined using Protocol Buffers (proto3), providing a language-agnostic contract for communication between the daemon (palyrad), the browser automation engine (palyra-browserd), the CLI (palyra), and various client SDKs. These definitions are located in schemas/proto/palyra/v1/ and are used to generate stubs for Rust, Kotlin, and Swift schemas/generated/rust/protocol_stubs.rs#1-5, schemas/generated/kotlin/ProtocolStubs.kt#1-5, schemas/generated/swift/ProtocolStubs.swift#1-5.

​
Core Service Architecture

The system is partitioned into specialized services, each responsible for a specific domain of the Palyra ecosystem. The palyra-daemon implements most of these services as a gRPC server, while palyra-browserd specifically implements the BrowserService crates/palyra-daemon/build.rs#24-35, crates/palyra-cli/build.rs#24-35.

​
Service Map: Code to Protocol

The following diagram maps the high-level system components to their corresponding Protobuf service definitions and key RPC methods. Diagram: Protocol Service Mapping Sources: schemas/proto/palyra/v1/gateway.proto#7-51, schemas/proto/palyra/v1/browser.proto#7-42, crates/palyra-daemon/build.rs#8-14

​
Gateway, Approvals, and Vault (gateway.proto)

The gateway.proto file defines the primary entry points for agent orchestration and security management.

​
GatewayService

The central interface for managing agent execution and session lifecycles.

​
ApprovalsService

Manages the human-in-the-loop (HITL) security flow. It tracks ApprovalRecord entities which represent pending or resolved requests for sensitive actions schemas/proto/palyra/v1/gateway.proto#31-35.

​
VaultService

Provides encrypted storage for secrets. Secrets are scoped to prevent cross-agent data leakage schemas/proto/palyra/v1/gateway.proto#37-42. Sources: schemas/proto/palyra/v1/gateway.proto#1-200

​
Browser Automation (browser.proto)

The BrowserService defines the interface for the palyra-browserd sidecar. It abstracts complex browser interactions into discrete RPC calls.

​
Session and Tab Management

​
Interaction Methods

The service provides high-level primitives that map to headless_chrome actions:

​
Security and Budgeting

The SessionBudget message enforces strict limits on browser resource usage, including max_navigation_timeout_ms, max_screenshot_bytes, and max_actions_per_session schemas/proto/palyra/v1/browser.proto#57-74. Sources: schemas/proto/palyra/v1/browser.proto#7-168

​
Shared Types (common.proto)

The common.proto file contains primitive types used across all services to ensure consistency in identification and event handling.

​
Identification

  • CanonicalId: A standard wrapper for ULIDs or UUIDs used to identify sessions, runs, and agents.
  • RunStreamEvent: The core union type for all events emitted during an agent execution, including log messages, tool calls, and status changes.

​
Entity Interaction Flow

The following diagram demonstrates how a request flows through the generated code entities. Diagram: Code Entity Data Flow Sources: schemas/generated/rust/protocol_stubs.rs#315-325, schemas/proto/palyra/v1/gateway.proto#9-10

​
Specialized Services

​
AuthService (auth.proto)

Manages AuthProfile entities and credential health. It supports OAuthCredential and ApiKeyCredential types schemas/generated/rust/protocol_stubs.rs#7-58.

​
NodeService (node.proto)

Handles distributed node registration and heartbeat.
  • RegisterNode: Used by remote executors to join the daemon’s control plane.
  • Heartbeat: Maintains mTLS session liveness.

​
Memory and Cron (memory.proto, cron.proto)

  • MemoryService: Provides vector-searchable long-term storage for agents.
  • CronService: Manages scheduled Routine executions, allowing agents to trigger actions based on temporal triggers.
Sources: schemas/proto/palyra/v1/auth.proto#1-50, schemas/proto/palyra/v1/cron.proto#1-30, schemas/proto/palyra/v1/memory.proto#1-30