palyrad), the browser automation service (palyra-browserd), and various clients including the CLI, Web Console, and Desktop application.
Protocol Versioning Strategy
Palyra uses a strict versioning scheme to ensure compatibility across its distributed components. The core of this system is thePROTOCOL_MAJOR_VERSION, which is incremented whenever breaking changes are introduced to the message structures or RPC signatures.
- Major Versioning: Defined in
schemas/generated/rust/protocol_stubs.rsasPROTOCOL_MAJOR_VERSION = 1schemas/generated/rust/protocol_stubs.rs#5-5. - Envelope Versioning: Most top-level messages include a
uint32 vfield (e.g.,v = 1) to allow for field-level evolution and runtime validation schemas/proto/palyra/v1/gateway.proto#86-86. - Validation: The daemon validates that incoming requests match the
CANONICAL_PROTOCOL_MAJORcrates/palyra-daemon/src/gateway.rs#22-22.
Service Architecture Overview
The protocol is divided into functional domains, each represented by a.proto file. These are compiled into language-specific stubs for Rust, Kotlin (Android), and Swift (iOS/macOS) schemas/generated/rust/protocol_stubs.rs#1-1, schemas/generated/kotlin/ProtocolStubs.kt#1-1, schemas/generated/swift/ProtocolStubs.swift#1-1.
Core Service Mapping
The following diagram maps the logical service definitions to their implementation entities within thepalyrad daemon.
Diagram: Service Definition to Implementation Mapping
Sources: schemas/proto/palyra/v1/gateway.proto#7-51, crates/palyra-daemon/src/gateway.rs#41-44
Gateway Service (gateway.proto)
The GatewayService is the primary entry point for agent orchestration and session management. It handles the lifecycle of “Runs” and message routing.
Key RPCs
RunStream: A bidirectional gRPC stream usingRunStreamRequestandRunStreamEventschemas/proto/palyra/v1/gateway.proto#9-10. This is the core mechanism for interactive agent sessions.RouteMessage: Dispatches inbound messages from various channels (CLI, Discord, Slack) to the appropriate agent schemas/proto/palyra/v1/gateway.proto#16-16.ListSessions/ResolveSession: Manages the state of active and historical orchestrator sessions schemas/proto/palyra/v1/gateway.proto#13-14.
Approval Subsystem
TheApprovalsService provides access to the audit log of security decisions.
ApprovalRecord: Contains details about the requester, the subject (e.g.,APPROVAL_SUBJECT_TYPE_TOOL), the decision, and theApprovalPolicySnapshotschemas/proto/palyra/v1/gateway.proto#85-106.ExportApprovals: A server-streaming RPC that allows for high-volume audit log extraction inNDJSONorJSONformats schemas/proto/palyra/v1/gateway.proto#34-34.
Browser Service (browser.proto)
The BrowserService defines the interface for palyra-browserd, the headless automation engine. It focuses on session-based web interaction with strict resource budgeting.
Session Management and Budgeting
Every browser session is governed by aSessionBudget to prevent resource exhaustion.
SessionBudget: Controlsmax_navigation_timeout_ms,max_screenshot_bytes, andmax_actions_per_sessionschemas/proto/palyra/v1/browser.proto#57-74.CreateSessionRequest: Includes security flags likeallow_private_targetsandaction_allowed_domainsschemas/proto/palyra/v1/browser.proto#76-91.
Interaction RPCs
The service provides granular control over the Chromium instance:Navigate/Click/Type: Standard web automation primitives schemas/proto/palyra/v1/browser.proto#19-21.Observe: Returns a snapshot of the DOM and accessibility tree schemas/proto/palyra/v1/browser.proto#29-29.RelayAction: Facilitates communication with the Palyra Browser Extension for “human-in-the-loop” browser actions schemas/proto/palyra/v1/browser.proto#40-40.
Supporting Services
Cron Service (cron.proto)
Manages scheduled routines.
CronJobRecord: Defines the schedule (Cron, Every, At), the prompt to execute, and theCronConcurrencyPolicycrates/palyra-daemon/src/journal.rs#232-248.- Status Tracking: Jobs transition through states like
Accepted,Running,Succeeded, orFailedcrates/palyra-daemon/src/journal.rs#185-192.
Memory Service (memory.proto)
Handles long-term storage and vector search for agent context.
MemoryItem: A unit of storage containing text, metadata, and optional embeddings crates/palyra-daemon/src/journal.rs#63-68.- Search: Supports top-K similarity search via the
MemorySearchRequestcrates/palyra-daemon/src/gateway.rs#64-67.
Vault Service (gateway.proto)
Provides a secure K/V store for secrets.
PutSecret/GetSecret: Standard secret management operations schemas/proto/palyra/v1/gateway.proto#38-39.- Scoping: Secrets are organized by
scopeandkeyschemas/proto/palyra/v1/gateway.proto#177-181.
Data Flow: Message Routing
The following diagram illustrates how aRouteMessageRequest flows from a protocol definition into the daemon’s internal logic.
Diagram: RouteMessage Data Flow
Sources: schemas/proto/palyra/v1/gateway.proto#16-16, crates/palyra-daemon/src/gateway.rs#50-54, crates/palyra-daemon/src/journal.rs#63-71
Common Message Types (common.proto)
The common.proto file defines primitive types used across all services to maintain consistency.
| Type | Purpose | Reference |
|---|---|---|
CanonicalId | A standardized ULID-based identifier for entities. | schemas/proto/palyra/v1/gateway.proto#87-89 |
MessageAttachment | Defines files or media attached to messages. | crates/palyra-daemon/tests/gateway_grpc.rs#134-134 |
ApprovalPrompt | The UI schema for requesting user approval. | schemas/proto/palyra/v1/gateway.proto#101-101 |
RunStreamEvent | The polymorphic event type for orchestrator updates. | schemas/proto/palyra/v1/gateway.proto#10-10 |