A durable execution engine for AI agent workflows.
Versioned DAGs · crash-safe workers · replayable events · observable costs
Important
Relay is an active pre-1.0 project. The durable runtime, operator console, production authentication boundary, OpenAI adapter, guarded MCP boundary, integration/browser suites, load harness, and public evaluation image are runnable. Review the documented single-owner and single-instance evaluation limitations before using it for sensitive production workloads.
Relay turns an immutable workflow definition into a durable, inspectable run. PostgreSQL owns the truth. NATS JetStream wakes workers up. Every claim is fenced, every retry is bounded, and every user-visible state change is recorded as a replayable event.
Relay is not a marketing page or a passive agent monitor. It is the operator console and execution runtime for defining immutable DAGs, submitting work, and watching durable state move through the system.
- Create validated LLM, tool, transform, and join workflows.
- Submit idempotent runs against deterministic mock or OpenAI providers.
- Watch the live dependency graph over replayable server-sent events.
- Inspect node state, retries, event history, tokens, and known cost.
- Cancel work durably without pretending remote side effects are exactly-once.
The product site is live at relay.jonzhang.dev and leads directly into the secured operator console. The separate build-status site records the public build and release milestones.
Most agent demos stop at orchestration. Relay starts where the happy path ends:
| Promise | How Relay earns it |
|---|---|
| Survives worker crashes | Leased attempts, fencing tokens, and recovery scans |
| Handles duplicate delivery | Transactional claims and stable message deduplication IDs |
| Explains every run | Append-only events, structured logs, attempts, traces, and usage |
| Executes DAGs concurrently | Dependency-aware scheduling with per-run and global limits |
| Controls AI risk | Typed outputs, budgets, deadlines, allowlisted tools, permission gates |
| Never overclaims | At-least-once dispatch; external side effects are not exactly-once |
The diagram is the canonical system map used across Relay's documentation and build dashboard. See Architecture, the OpenAPI 3.1 contract, and ADR-0001.
Start the backend stack with:
cp .env.example .env
docker compose up --buildOpen the product site at http://localhost:3000 or go directly to the console at http://localhost:3000/console, then verify the API:
curl http://localhost:8080/api/v1/health/readyThe console creates workflows and submits real runs; it does not seed fake metrics. In production set RELAY_ENV=production and provide a one-line RELAY_API_KEY (or mounted RELAY_API_KEY_FILE) with at least 32 random characters. Development mode uses the configured local developer identity.
The deterministic mock model is the default. To opt into OpenAI, set RELAY_PROVIDER=openai and provide OPENAI_API_KEY or mount a secret file through OPENAI_API_KEY_FILE; follow the paid-provider smoke-test procedure. Optional structured outputs are checked again locally after the provider responds. Pricing is loaded only from a versioned file selected by RELAY_PRICING_FILE; config/pricing.example.json intentionally contains no invented rates, so unknown costs stay unknown. Tool nodes remain fail-closed unless RELAY_MCP_CONFIG_FILE points to an explicit connection and tool allowlist; use config/mcp.example.json as the schema. Secrets are referenced by environment-variable name and are never stored in workflow JSON.
define immutable version
↓
submit run + idempotency key
↓
schedule ready nodes in one database transaction
↓
publish outbox records to JetStream
↓
claim fenced attempt → execute → commit completion
↓
append event → unlock dependants → stream replay to UI
- PostgreSQL is authoritative; JetStream is a dispatch accelerator.
- A worker completion is accepted only for the current lease fencing token.
- Run and node transitions are explicit and validated.
- Cancellation is durable and prevents new work; already-started external side effects may still finish.
- Pricing is configuration, not code. Unknown model pricing produces unknown cost, never a guess.
cmd/api HTTP API and SSE
cmd/controlplane scheduler, outbox dispatcher, recovery
cmd/worker isolated node executor
internal/domain workflow and state-machine invariants
internal/store PostgreSQL transactions and generated queries
internal/ai model provider boundary
internal/mcp allowlisted tool execution
internal/telemetry traces, metrics, structured logging
migrations Goose SQL migrations
web Next.js developer console
examples runnable workflow definitions
deploy local and production deployment assets
docs architecture, ADRs, threat model, operations
Relay targets Go 1.27.4, Node.js 24, PostgreSQL 17+, and NATS JetStream. Local development is container-first so host toolchain drift does not change test results.
make bootstrap
make test
make devExact commands and verified results are recorded as milestones land. See Implementation plan for scope and acceptance gates.
Relay provides durable state transitions and duplicate-safe execution bookkeeping. It deliberately does not claim exactly-once execution or exactly-once external side effects. Tool authors should provide idempotency keys or compensating actions when a side effect matters.
- Credentials are referenced, never embedded in workflow JSON.
- LLM and tool output is untrusted and size-bounded.
- Remote MCP endpoints are allowlisted and protected against SSRF.
- Side-effecting tools require an explicit permission decision.
- Logs, traces, and API errors pass through redaction.
See the acceptance-gated threat model and deployment hardening guide before exposing Relay to a network.
| Area | Status |
|---|---|
| Architecture and ADRs | 🟢 Implemented |
| Domain invariants | 🟢 Implemented and unit tested |
| Durable scheduler and recovery | 🟢 Crash window, lease recovery, active cancellation, run/node deadlines, cost budgets, stale completion, and duplicate claims integration-tested |
| OpenAI adapter | 🟢 Implemented and contract tested |
| MCP adapter | 🟢 Allowlist, schema, approval, SSRF, timeout, redaction, and size gates contract-tested |
| Developer console | 🟢 Authoring preview, immutable DAG viewer, live runs, attempts, searchable events, retries, usage, and settings |
| Production authentication | 🟢 Constant-time bearer validation and encrypted HttpOnly console sessions |
| Observability | 🟢 Prometheus metrics and optional OTLP/HTTP traces across all services |
| OpenAPI 3.1 | 🟢 Published and linted |
| Integration, browser, and load tests | 🟢 Passing; factual local benchmark results published |
| Public deployment | 🟡 Render image and Blueprint smoke-tested; cloud provisioning requires operator credentials |
Small, reviewable commits are preferred. Start with CONTRIBUTING.md, preserve the durability invariants, and include a test that would fail without your change.