Relay files and sync

The relay file, where it is edited, and running relays locally and in the cloud.

Relay files

A relay is gemmein/relays/<name>.json, and your AI writes it. It names one trigger and one to ten actions, which run in order.

The name is two to sixty-three lowercase letters, digits and hyphens, starting with a letter. It is the file name and the last segment of the receiver URL, so renaming a relay renames its URL. An unknown field returns invalid_definition, with one sentence per problem that names the field. Fix the JSON from that sentence.

In the dashboard, the Webhooks page is where you create, edit (the definition JSON), pause, resume, replay, rotate and delete relays. It shows the receiver URL, the secrets, every event with each action's result, and where the definition came from: a file (and when it synced) or an edit on that page (and when).

Local development and sync

gemmein dev runs receivers, schedules and record changes on your machine the same way the cloud does. The boot card prints each receiver's local URL, and every run prints RELAY · name · trigger · n actions · ok|failed.

npx gemmein sync copies the relay files to the cloud app's Development environment with the collections. Sync copies definitions and never data. Secrets never sync: a receiver secret created on your machine stays there, and the cloud creates its own and shows it once in the dashboard.

After going live, npx gemmein sync --live copies relays and AI tools into the Live environment. It prints what would change, then asks for its own browser approval: your human opens the link it prints, checks the code, reads every relay, tool and alias it will write, and approves, with the code Gemmein emails. The approval covers that one push, within 10 minutes. It never deletes, and asks before replacing a relay edited in the dashboard.

A relay’s trigger kind can change freely under gemmein dev. Once synced, the cloud refuses the change and names the two ways out: rename the relay, or run npx gemmein sync --prune in Development.

A relay's name is fixed once created, because the receiver URL is built from it.