Skip to main content
This page documents the Palyra protocol definition layer, which serves as the “source of truth” for all inter-process communication (IPC) and network boundaries. The system utilizes Protocol Buffers (Protobuf) to define service interfaces and data structures, which are then compiled into native stubs for Rust, Kotlin, and Swift to ensure type safety across the daemon, mobile, and desktop applications.

​
Protocol Architecture and Schema Definitions

Palyra’s protocol is versioned and modularized into functional domains. The schemas are located in the schemas/proto/palyra/v1/ directory.

​
Core Schema Modules

ModulePurposeKey Services / Messages
common.protoFundamental primitives used across all other schemas.CanonicalId (ULID), MessageEnvelope, JournalEvent, ToolProposal.
gateway.protoThe primary interface for the palyrad daemon.GatewayService, ApprovalsService, VaultService, CanvasService.
browser.protoInterface for the palyra-browserd automation service.BrowserService, SessionBudget, RelayAction.
auth.protoManagement of credentials and authentication profiles.AuthServiceClient, OAuthCredential, AuthHealthSummary.

​
Data Flow and Service Mapping

The following diagram illustrates how the .proto definitions map to the runtime components and the generated code entities. Protocol Entity Mapping Sources: schemas/proto/palyra/v1/common.proto#1-11 | schemas/proto/palyra/v1/gateway.proto#1-29 | schemas/proto/palyra/v1/browser.proto#1-37

​
Multi-Language Stubs

To support the polyglot nature of the Palyra ecosystem (Rust daemon, Kotlin Android, Swift iOS/macOS), the project generates static stubs. These stubs provide a native API for interacting with gRPC services and serializing/deserializing protocol messages.

​
Generated Stub Locations

​
Service Implementation Example: BrowserService

The BrowserService defined in browser.proto is the primary interface for the palyra-browserd crate. Browser Service Implementation Flow Sources: schemas/proto/palyra/v1/browser.proto#7-37 | crates/palyra-browserd/Cargo.toml#28-29 | schemas/generated/rust/protocol_stubs.rs#61-171

​
Protocol Validation and CI Pipeline

Palyra maintains strict protocol coherence through a validation pipeline executed during CI. This ensures that any change to the .proto files is backward compatible and that generated stubs are always in sync with the source schemas.

​
Validation Scripts

The validation logic is split into schema verification and stub compilation checks:
  1. Schema Validation: scripts/protocol/validate-proto.ps1 uses protoc to verify that the .proto files are syntactically correct and can be compiled into a descriptor set. scripts/protocol/validate-proto.ps1#58-66
  2. Coherence Check: scripts/protocol/check-generated-stubs.ps1 runs the generator and checks for git diffs in the schemas/generated directory. If a developer modifies a .proto file but forgets to update the stubs, the CI will fail. scripts/protocol/check-generated-stubs.ps1#14-21
  3. Language-Specific Compilation:

​
Rust Build Integration

For the Rust crates specifically, the protocol compilation is often integrated into the build.rs script. For example, palyra-browserd uses tonic-prost-build to compile its specific requirements at build time, ensuring the local crate is always using the latest definitions from schemas/proto. Sources: crates/palyra-browserd/build.rs#14-17 | crates/palyra-browserd/Cargo.toml#34-37

​
Key Data Structures

​
Canonical Identifiers (ULID)

Palyra uses ULIDs (Universally Unique Lexicographically Sortable Identifiers) for all primary keys. In the protocol, these are represented by the CanonicalId message.

​
RunStream and Event Journaling

The core of the agent interaction is the RunStream. It is a bidirectional gRPC stream where the client sends a RunStreamRequest (containing user input or tool approvals) and the server responds with a stream of RunStreamEvent messages. Sources: schemas/proto/palyra/v1/common.proto#259-276 | schemas/proto/palyra/v1/gateway.proto#7-29