Most services running across my home lab are small utilities: nightly backup syncs, agentic workflows, automation and sensor telemetry pipelines. They do not process millions of requests, but they do require durability. When an unexpected power blip (the ones where you accidentally turn off the wrong switch) or reboot hits a machine midway through syncing a dataset, the job must resume from its last completed step rather than restarting from zero or leaving partial state behind.
DBOS offers an appealing execution model for this. Rather than requiring heavy workflow orchestration engines with dedicated worker fleets, it compiles durable steps directly into application code across TypeScript, Python, Go, and Java. You write standard functions, tag them as steps, and the runtime handles persistence in a database.
The data plane handles this well: your application records step inputs, outputs, and completion state directly in its own database. The catch came when connecting those applications to a centralized control plane. This is the tale of Relay.
MOTIVATION
Friction in Small-Scale Setups
While the DBOS data plane records steps in your local database, coordinating distributed execution requires a control plane. In the DBOS model, the control plane coordinates executor presence leases, dispatches distributed cron triggers, orchestrates recovery when an executor node dies, and provides a unified dashboard for inspecting workflow state across machines.
In the upstream DBOS stack, those duties belong to Conductor. DBOS Transact is open source, but Conductor is proprietary software. For homelabs, hobby clusters, and small setups, requiring developer keys and a proprietary license for modest workloads was a dealbreaker. This extends to solo developers and small teams as well.
My checklist was straightforward:
- Local development needs to work out of the box on a laptop as a single binary with zero external services.
- The central instance in my home lab must operate without external authentication tokens, phone-home telemetry, or vendor registration.
- Protocol and wire compatibility must remain exact so unmodified DBOS applications function simply by pointing their Conductor URL at my server.
- Operational data, step outputs, and execution history stay entirely on my own disks.
Because no existing project solved this, I built Relay.
A worthy mention: If you only want a read-only dashboard, you should take a look at DBOS Argus, it is quite a nifty project that lets you visualize your workflows.
VERIFICATION
Clean-Room Protocol Conformance
Development followed clean-room principles derived strictly from public materials: published OpenAPI 3.0 specifications, documented WebSocket protocol frames, and public SDK client code. Relay implements the complete 32-message Conductor wire protocol over /websocket/{appName}/{conductorKey}. No proprietary Conductor binaries or console container images were ever run, decompiled, or inspected.
Compatibility cannot rely on optimistic assumptions. Relay proves wire compatibility through an automated multi-SDK conformance test suite run against unmodified applications in Go, Python, TypeScript, and Java.
The test suite validates seven operational tiers:
- Socket connection and presence: executors connect over WebSocket, establish presence leases, and maintain periodic heartbeats.
- REST API and schema conformance: workflow query endpoints, queues, schedules, and token routes adhere strictly to upstream status codes and payload schemas.
- Data-plane isolation: workflow metadata queries use official SDK client libraries without direct raw SQL against application database tables.
- Field byte parity: workflow status fields, application versions, and serialized JSON inputs match upstream SDK outputs down to byte representation.
- Chaos failover and recovery: primary executors are killed abruptly with SIGKILL mid-workflow. Relay observes executor disconnection, waits out the configured grace period, transitions the executor to DEAD, and dispatches recovery to active secondary containers. Surviving nodes pick up pending workflows and finish them without repeating steps.
- Offline cancel and resume: operator cancellations and resumptions execute through native data-plane endpoints and reflect accurately in workflow states.
- Step-level workflow forking: completed or failed workflows can branch from an arbitrary step index with modified inputs, executing to completion while preserving parent lineage.
Executing these tests against all four language SDKs running in parallel under Podman verifies that an unmodified application connected to Relay behaves identically to one connected to the upstream service.
STORAGE STRATEGY
The Dual-Engine Strategy
Operational requirements vary across environments: a quick test run on a laptop demands zero dependencies, edge homelab nodes need lightweight replication, and multi-host fleets require strict distributed concurrency controls.
Relay reconciles this through a dual-engine architecture: an embeddable, SQLite-compatible tier for local development and edge nodes, alongside a PostgreSQL tier for distributed high-availability fleets.
Pure-Go SQLite and libSQL for Local Dev and Edge
Starting a workflow test shouldn't require spinning up a PostgreSQL container or managing database credentials. Relay embeds a pure-Go SQLite driver based on modernc.org/sqlite, which requires no CGO toolchain and keeps the control plane self-contained inside a single static executable:
For homelab edge nodes that outgrow a single local file, Relay supports Turso via libSQL. Because libSQL preserves SQLite wire and dialect compatibility, you gain distributed replication across edge nodes without the operational overhead of running a full database cluster.
Clustered PostgreSQL for High-Availability Fleets
When scaling to multi-executor fleets across redundant hosts, the storage layer switches to PostgreSQL via the native pgx driver. PostgreSQL delivers transactional row-level lease fencing, native jsonb indexing for fast step lookups, and concurrent state transitions across active Relay instances.
A single configuration flag determines the backend, allowing a project to start with zero infrastructure on embedded SQLite and graduate to PostgreSQL as scale and availability requirements dictate.
OPERABILITY
Features Built for Real Operations
Matching the wire protocol is only the baseline. Relay builds operational tools into the server to make running workflows transparent.
Embedded Web Dashboard and Family DAGs
The web dashboard ships directly inside the binary. Pointing a browser at http://localhost:8090 exposes:
- Real-time workflow status tables with pagination, status filtering, and search.
- Interactive SVG workflow family DAGs showing parent workflows, child steps, and parallel branches.
- Detailed step execution inspectors displaying start timestamps, latencies, retry counts, and input/output payloads.
- An event trace log tracking WebSocket transitions, executor registrations, and heartbeat health.
The console loads without external CDN assets or separate Node.js server processes. In local development mode, authentication is disabled by default so workflows can be examined immediately.
Declarative GitOps via CLI
Managing application registrations, cron schedules, queue configurations, and alert rules through web forms creates configuration drift. Relay includes built-in declarative management commands:
This allows homelab automation and team infrastructure to track workflow control plane configuration directly in git repositories.
GETTING STARTED
Deployment and Quickstart
Relay distributes as a single static binary for Linux, macOS, and Windows, alongside container images and Docker Compose templates.
To start Relay with Docker and PostgreSQL:
To point your unmodified DBOS application to Relay, set the standard DBOS Conductor environment variables:
# Standard DBOS environment variables for TypeScript, Python, Go, and Java
export DBOS__CONDUCTOR_URL="ws://localhost:8090"
export DBOS__CONDUCTOR_KEY="local"
export DBOS__APP_NAME="order-service"Your application connects to Relay on startup over WebSocket, registers its executor ID, and begins processing durable workflows.
PLAYGROUND
The In-Browser WASM Playground
To let developers evaluate DBOS durable execution without installing runtimes, compilers, or local databases, Relay provides an in-browser playground on the project documentation site.
The playground runs client workflow simulations entirely in WebAssembly using PGlite in the browser. You can trigger multi-step workflows, inspect step memoization live, inject errors to observe retries, and watch how the DAG updates as steps transition from pending to success, all without touching your local machine.
The playground interface provides:
- A compact control bar with immediate workflow execution buttons.
- A folding live sidebar for monitoring executor connections and hub state.
- A syntax-highlighted code viewer displaying the underlying workflow implementation.
- Real-time execution logs showing exact step execution durations and payload schemas.
Relay is open-source under the MIT license and developed in public on GitHub. Prebuilt single-binary releases, container images, and deployment guides are available in the project repository.
It is my hope that this enables more solo developers and small teams to try DBOS and make it a foundational piece of their stack.
