Architecture & engineering decisions
From a goal to a durable graph.
Relay implements scheduling, persistence and failure recovery itself. Model APIs and coding agents sit behind a small provider interface.
Start only the work that is ready.
A goal goes through a planner, then the same validation as a hand-written graph. Unknown references, duplicate ids and cycles are rejected. The scheduler resolves saved outputs into prompts and launches ready steps up to the concurrency limit.
Independent branches run together. Each completed result is saved before dependent work can use it.
As soon as a step settles, the engine checks readiness again. A slow branch does not hold back a different branch whose inputs are already available.
Read the schedulerA checkpoint survives the worker.
Heartbeats renew the lease. If a worker disappears, a later request can take over after expiry. Fenced writes stop the old worker from saving results once it loses ownership. An interrupted call can run again; a saved successful step is preserved.
bun run demo:crash
This reproducible demo runs two engines on one database and kills the first mid-step.
An agent loop is one piece of the workflow.
Pi, Claude Code and Codex manage conversations and tools. Relay coordinates independent invocations, routes dependencies and persists their results. It does not claim to reproduce their internal implementations.
| Integration | Input / output | What Relay handles |
|---|---|---|
| Pi | Stdin prompt, JSON events | Final assistant message and per-message usage |
| Claude Code | Print mode, JSON result | Result, structured output, errors and usage |
| Codex | Exec mode, JSONL events | Completed agent message and turn usage |
| Model APIs | HTTPS request, provider response | Prompt, validated output, retries and cost estimate |
The local example fans out to all three agents, then joins their analyses. Each subprocess uses argument arrays, bounded output, cancellation, and read-only tools or a read-only sandbox. No website request launches a command on the server.
bun run demo:agents
Install and authenticate the CLIs first. Claude Code’s bare mode requires an API key. Pi’s tool allowlist is not an operating-system sandbox.
Your keys belong to your workspace.
A random HttpOnly cookie identifies this browser workspace. Every run, event and connection request checks its owner on the server. Keys are validated with the selected provider and encrypted with AES-256-GCM before being saved. They are never included in run exports or connection listings.
Browser storage does not hold your keys. Clearing the workspace cookie loses access; this release has no account recovery or cross-device sign-in. Remove connections when you finish using a shared machine.
Manage connectionsThe boundaries are part of the design.
- At-least-once execution. A worker can die after an upstream call but before saving its response. Side-effecting tools require idempotency and external isolation.
- Request-driven continuation. On Vercel, long runs resume when another request arrives after the lease expires. Unattended jobs need a separate persistent worker.
- Estimated budgets. Token usage comes from providers. Dollar estimates use your configured prices; in-flight calls can exceed a budget.
- Visible simulations. Demo responses are scripted. They demonstrate the real scheduler and persistence without claiming model quality or current research.