openfabriq
Deployment

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.

Slack, Linear, Sentry, a deploy…
Online services
  • call, or are asked every minute
a signed webhook
The relay
Your Cloudflare account or your server
  • always on
  • checks who sent it
  • keeps each event up to 7 days
the engine connects and collects
The engine
Your computer or a server
  • runs the agents
  • writes to GitHub
The engine opens the connection to the relay, never the other way: your machine stays closed.

Do you need it?

You useRelayWhy
GitHub, schedulesnot neededthe engine reads GitHub with gh every minute
Slack mentionsrequiredSlack's Events API posts each mention to the relay
Linear labels and delegationrequiredthe openfabriq app in Linear posts a webhook to the relay
Sentryrequiredthe relay asks Sentry for new issues every minute
Webhooks from another service (a deploy platform, Stripe, an uptime monitor)requiredthe sender only calls

One relay serves one engine, whatever the number of factories it runs.

Where to host it

CloudflareYour own server
What runsa Worker and one Durable Object on your Cloudflare accountthe same code in workerd, in Docker
Setupone commanda domain, ports 80 and 443, docker compose up -d
CostCloudflare's free plan is enough for a team's volumeyour server
Upalwayswhen 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 login

Deploy and connect

openfabriq connect relay

It 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.yaml

Restart 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

  1. 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 query passed as is.
  2. 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 503 and Retry-After: 60.
  3. 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.
  4. 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 connect gives 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.

On this page