Relay
A mailbox on the Internet for your factory, so that Slack, Linear, Sentry or any webhook can reach it while your machine cannot be reached.
Your engine cannot be called from the Internet: no public address, no open port, on purpose. It goes and asks GitHub every minute with gh, like checking a mailbox. Other services call: they post each event at once to an address you gave them, a webhook, and expect an answer within seconds (Linear within 10). Your engine has no address to give, and a sleeping laptop would not answer.
The relay is that address: a small program you deploy once, on your Cloudflare account or your own server, that is always up. Services drop their events there at any time; your engine collects them whenever it is on.
- call, or are asked every minute
- always on
- checks who sent it
- keeps each event up to 7 days
- runs the agents
- writes to GitHub
Do you need it?
| You use | Relay | Why |
|---|---|---|
| GitHub, schedules | not needed | the engine reads GitHub with gh every minute |
| Slack mentions | required | Slack's Events API posts each mention to the relay |
| Linear labels and delegation | required | the openfabriq app in Linear posts a webhook to the relay |
| Sentry | required | the relay asks Sentry for new issues every minute |
| Webhooks from another service (a deploy platform, Stripe, an uptime monitor) | required | the sender only calls |
One relay serves one engine, whatever the number of factories it runs.
Where to host it
| Cloudflare | Your own server | |
|---|---|---|
| What runs | a Worker and one Durable Object on your Cloudflare account | the same code in workerd, in Docker |
| Setup | one command | a domain, ports 80 and 443, docker compose up -d |
| Cost | Cloudflare's free plan is enough for a team's volume | your server |
| Up | always | when your server is |
Cloudflare is the simplest, with nothing to maintain; your own server suits a team that already runs the engine in Docker and wants everything in one place.
You need a Cloudflare account. The openfabriq command carries the relay's code: no sources to download.
Log in to Cloudflare
npx wrangler loginDeploy and connect
openfabriq connect relayIt checks that Wrangler is logged in, draws a random ENGINE_TOKEN, deploys the Worker openfabriq-relay with it, checks /health and the connection, and saves the address and the token in ~/.openfabriq/secrets.json:
Deploying the relay to your Cloudflare account...
Relay connected: https://openfabriq-relay.<your-subdomain>.workers.dev. Token saved in /home/you/.openfabriq/secrets.json.
If "openfabriq start" is running, restart it (Ctrl-C, then "openfabriq start"): it reads the connections when it starts.
Next: "openfabriq connect slack", "linear" or "sentry", or "openfabriq connect webhook <name>".If Cloudflare says your account has no workers.dev subdomain yet, open the dashboard's Workers & Pages page once, then run the command again.
To update it, update openfabriq, then run openfabriq connect relay again. It redeploys with a new token; events waiting in the queue are kept.
Connect services through it
openfabriq connect slack # Slack mentions
openfabriq connect linear # Linear labels and delegation
openfabriq connect sentry # Sentry's new issues
openfabriq connect webhook <name> # a webhook of factory.yamlRestart openfabriq start: it connects to the relay when a factory listens to a service, tells it which Sentry projects to watch, and says so when the relay is missing. To check the relay:
curl https://<your-relay>/health
# {"ok":true}How it works
- Receive. The relay checks the signature, the proof that the event comes from Linear, Slack, GitHub, Sentry, Stripe or a Standard Webhooks sender, and answers at once. Sentry is asked instead, every minute, with each automation's
querypassed as is. - Keep. The event goes into a queue that survives restarts; a delivery already received is not kept twice. Past 10,000 events or 100 MB waiting, new deliveries get
503andRetry-After: 60. - Deliver. Your engine opens a connection with a token only the two of them know (
ENGINE_TOKEN) and keeps it open. The relay hands over what waited, then each new event. A confirmed event is deleted, an unconfirmed one comes back at the next connection, one never collected is deleted after 7 days: services' data (an issue's text, a webhook body) is never kept longer. - Finish a Linear install. Installing openfabriq as an agent in Linear ends in the browser, on an address that must be online: the relay's, which receives Linear's tokens, keeps them and refreshes them.
Is it safe?
- It decides and writes nothing. It never runs an agent, chooses an automation, reads your repository, or writes to GitHub, Slack or Sentry: that stays in the engine. One exception: a fixed "Received" note in a Linear agent session, because Linear wants an answer within seconds and the engine may be asleep.
- Every route is closed except
/health: the rest needs the engine's token, the sender's valid signature, or, to finish a Linear install, a one-time code the relay gave out. - Its only own secret is
ENGINE_TOKEN.openfabriq connectgives it the others later, kept in its storage: Linear's, Slack's, your webhooks', the Linear app's token (it can write in Linear on openfabriq's behalf) and your Sentry token (sent only to your Sentry). Revoke either token at any time, in Linear or in Sentry. Slack's bot token stays on your machine. - Its content is data. Like everything that reaches an agent, an event is marked as data, never as instructions.