Relay documentation

Relay is an open-source control plane for DBOS Transact applications, compatible with the Conductor executor protocol and HTTP API. It is not affiliated with or endorsed by DBOS, Inc.

This is an Open Knowledge Format v0.2 bundle: a human- and agent-readable wiki covering the project's public design, architecture, decisions, and contribution guidance. It is maintained to reflect status quo as the project evolves. The working specification is held outside this bundle.

The project implementation is in progress. Sections describe the architecture, protocol, and operational usage of Relay.

Getting started

• Overview - what Relay is and why it exists
• Contributor guide - how to contribute
• Clean-room rules - the sourcing rules that bind every contributor

Usage

• Usage overview - how to run and operate Relay
• Quickstart - run Relay locally with Postgres
• Declarative operations - fleet configuration with relay.yaml, apply, and diff
• Operations and migrations - schema migrations, rolling upgrades, and rollbacks
• Conformance testing - run the automated Conductor conformance test suite

Testing

• Testing overview - verification matrices and test suites
• Multi-SDK verification - test matrix across Python, TypeScript, Go, and Java SDKs

Discovery

• Discovery overview - initial discovery findings
• Provenance ledger - permitted sources for every claim
• REST surface - HTTP API operations and inventory
• Authorization - permission model and key format
• Client behaviour - dbosctl conformance notes
• Dashboard reuse - UI assessment and go/no-go decision
• Recovery timing - heartbeat, grace periods, and overrides
• Metrics and alerting - OpenMetrics catalogue and alert rules

Protocol

• Protocol overview - executor WebSocket protocol specification
• Executor WebSocket protocol - wire messages and liveness
• Wire to REST mapping - mapping wire records to OpenAPI schemas

Design

• Design overview - the high-level approach
• Goals and non-goals - what v1 does and does not cover
• Compatibility tiers - the milestone gates
• Terminology - the canonical vocabulary

Architecture

• Architecture overview - components and layout
• Components - the module boundaries
• Recovery - executor liveness and recovery

Decisions

• Architecture decision records - decision records

Contribution

• Contribution overview - guides for contributors and maintainers

Repository contract

AGENTS.md holds the operational contract for humans and agents. This wiki never contains internal names, codenames, hostnames, absolute paths, tokens, or task identifiers, and the project's internal progress log is not part of it.

Knowledge base

• Changelog - software release notes managed by Release Please
• Documentation log - how this wiki has evolved