An open-source control plane for DBOS Transact applications, compatible with the Conductor executor protocol and HTTP API. Self-hostable, MIT licensed, and not affiliated with or endorsed by DBOS, Inc.
DBOS Transact applications persist their workflow execution state in their own application database and recover workflows locally when the owning process restarts. Distributed cross-node recovery, fleet monitoring, centralized telemetry, step DAG visualizations, and scheduled executions rely on a control plane. Relay is that control plane, engineered in the open under the MIT license.
Relay connects to DBOS applications in two ways. Attached mode speaks the Conductor executor protocol, for SDK releases that still ship the connector and for Java. Direct mode reads and controls workflows through the application's own system database using DBOS's MIT client, so it works with post-split SDK releases in the supported schema window. See Supported SDKs for the exact boundaries and Direct mode for the operator guide.
Read the announcement post: Relay: An Open-Source Control Plane for DBOS Applications.
| Workflow Family DAG | Fleet & Applications |
|---|---|
- Dual-Engine Storage (ADR 0011): Pure-Go embedded SQLite (
modernc.org/sqlite) for zero-dependency local development and single-node instances, plus PostgreSQL for clustered, multi-instance production deployments. - Conductor Protocol Parity in Attached Mode: Complete 33-message bidirectional WebSocket protocol support, verified against the official DBOS Transact SDKs up to the supported Attached ceiling.
- Direct Mode: Observe and control workflows through the application's own system database using DBOS's MIT client, with no connector, no enterprise package, and no vendor key. Works with post-split SDK releases across the supported schema window.
- Zero Application Changes: Neither mode requires an upstream SDK modification or a custom wrapper. Attached mode uses standard DBOS environment variables; Direct mode needs a database connection and, for automatic recovery, a liveness signal from the deployment.
- Embedded Web Dashboard: Self-hosted operations console on port 8090 with interactive SVG workflow DAG family visualization, execution curves, canvas viewport (pan/zoom), step history, real-time Server-Sent Events (SSE) telemetry, schedule management, and alerting rules.
- Declarative Fleet Management: Manage applications, queues, and alert policies declaratively via
relay.yamlwithrelay applyandrelay diff. - High Availability & Lease Fencing: Multi-node coordination with distributed leases, heartbeat tracking, automatic orphan reconciliation, and peer proxy forwarding.
- Clean-Room Derivation: Clean-room implementation derived solely from permitted public specifications and observable client contracts without proprietary artifacts.
Run Relay with pure-Go embedded SQLite storage (no PostgreSQL or Docker required):
# Download the binary
curl -fsSL https://github.com/abn/dbos-relay/releases/latest/download/relay-linux-amd64 -o relay
chmod +x relay
# Start Relay in embedded mode
./relay serve --embedded
# Open http://localhost:8090 in your browser to access the dashboardTo try Relay without installing anything, open the in-browser playground, which runs client-side workflow simulations entirely in the browser.
# Run standalone embedded container
podman run -d \
--name relay \
-p 8090:8090 \
ghcr.io/abn/relay:latest serve --embeddedOr connect Relay to an external PostgreSQL instance:
podman run -d \
--name relay \
-p 8090:8090 \
-e RELAY_DATABASE_URL="postgres://user:pass@postgres:5432/relay?sslmode=disable" \
ghcr.io/abn/relay:latest servePoint your DBOS Transact applications to Relay using standard configuration:
# Python
export DBOS_APP_NAME="orders-service"
export RELAY_URL="ws://localhost:8090"
export RELAY_API_KEY="your-api-key"
python3 main.py
# TypeScript
export DBOS_APP_NAME="orders-service"
export RELAY_URL="ws://localhost:8090"
export RELAY_API_KEY="your-api-key"
npm start
# Go
export DBOS_APP_NAME="orders-service"
export RELAY_URL="ws://localhost:8090"
export RELAY_API_KEY="your-api-key"
go run .These settings use Attached mode. Post-split SDK releases no longer contain the connector, so they cannot use these settings. Use Direct mode for those releases; see Supported SDKs for the schema window.
The project wiki is maintained in docs/ as an Open Knowledge Format (OKF v0.2) bundle:
- Overview: Project scope, architecture, and background
- Migrating from Conductor: Move an application to Attached or Direct mode
- Design & Compatibility Tiers: Verification tiers and conformance gates
- Architecture: Module boundaries, recovery lifecycle, and data-plane access
- Doctor preflight: Read-only migration and production readiness checks
- Executor WebSocket Protocol: Wire specification and frame formats
- Architecture Decision Records (ADRs): Technical decisions and design rationale
- Software Changelog: Release history managed by Release Please
- Documentation Update Log: Evolution and provenance log of the knowledge base
- Clean-Room Rules: Permitted sources and contributor rules
Relay enforces automated conformance and quality gates across all supported SDKs:
# Run full quality gate (lint, vet, unit tests, code generation drift)
make check
# Run end-to-end multi-SDK conformance matrix (Python, TypeScript, Go, Java)
make verify-sdk
# Run live database conformance battery against PostgreSQL
RELAY_TEST_DATABASE_URL="postgres://relay:relay@localhost:5433/relay?sslmode=disable" make verify-liveContributions are welcome. Please read the contributor guide, the clean-room rules, and AGENTS.md before submitting pull requests.
MIT. See LICENSE.