How to use Relay.

This example proves that Relay can detect a real change and write a real output. It requires only a plain-text file and Python 3.9 or newer.

1. Create a source file. Save a UTF-8 text file named relay-test.txt on your computer. Put Version 1 inside. Note its actual path; on macOS it might be ~/Desktop/relay-test.txt, while on Windows it might be C:\Users\YOUR_NAME\Desktop\relay-test.txt. Your Desktop location may differ, particularly with cloud sync.
2. Choose the recipe. Select File integrity. Under Job specification, enter the actual file path, keep Content actually changes, choose Archive changed local file, set a dedicated output folder such as ./relay-test-output and leave Safe first observation checked.
3. Rehearse in the browser. In the Decision Lab, click Run the three-step walkthrough. With safe baseline enabled, expect a held baseline, a held duplicate and a triggered change. This is a simulation using sample data, not a read of your actual file.
4. Export and extract. Use Download working automation ZIP. Extract it into its own folder and open a terminal there. The ZIP contains relay_runner.py, relay_config.json, README.txt and LICENSE.txt.
5. Execute three checks. Run the --once command shown in chapter 04. The first run stores the baseline. Run it again without changing the file: no event should fire. Now replace the file content with Version 2 and run it once more: one change event and a snapshot should be written.

Why this matters: A working interface is not evidence of a working automation. The archived file and the event ledger are the proof that the exported runner performed an action.

Relay watches one source per job. The source determines which rules make sense; the output determines what is written when a rule passes. All remote sources must be publicly accessible over HTTPS (local HTTP is permitted for localhost).

What can an action produce?

JSONL event record writes structured events to events.jsonl. Markdown research note writes a short source-linked note under notes/. CSV dataset row appends to events.csv. Archive changed local file writes a text snapshot under snapshots/ and is available only for local files. Every job also keeps its state and run history.

Check every controls the interval when you use --watch. Output folder is a path on your own machine; a relative path is resolved from the directory where the Python process starts. Use a different output folder for each independent job.

The Decision Lab evaluates editable sample content against your rule. Its purpose is to make the decision observable before the worker is deployed; it never writes your local output or dispatches a webhook.

Use Run the three-step walkthrough to compare a first observation, an unchanged repeat and a meaningful change. With Safe first observation enabled, the expected pattern for the file-change example is HOLD → HOLD → TRIGGER. Use Inject failure to confirm malformed evidence is rejected. The Flight Recorder explains each gate and the Evidence Report can preserve the rehearsal outcome.

Why thresholds do not fire repeatedly: A value staying above 5 is not a fresh crossing every five minutes. A numerical rule triggers when the condition changes from false to true. Likewise, a repeated feed item is not a new publication.

After exporting, extract the ZIP and open a terminal in the extracted directory containing relay_runner.py and relay_config.json. The worker uses the Python standard library; there is no pip install step.

python3 --version
python3 relay_runner.py --config relay_config.json --dry-run
python3 relay_runner.py --config relay_config.json --once

py -3 --version
py -3 relay_runner.py --config relay_config.json --dry-run
py -3 relay_runner.py --config relay_config.json --once

What is inside the export?

relay_config.json stores the selected source, rule, interval and action. relay_runner.py performs the real work. README.txt documents operation and LICENSE.txt provides the MIT licence. Export JSON config saves only the configuration; it is not a runnable automation on its own.

Relay is local-first, not a hosted 24/7 service. The website can be closed after export. Monitoring continues only while your Python process runs or an operating-system scheduler launches it on a powered-on computer or server.

Continuous mode while a terminal stays open

python3 relay_runner.py --config relay_config.json --watch

On Windows, replace python3 with py -3 if needed. Stop with Ctrl+C. Closing the terminal or shutting down the device stops this mode.

Scheduled execution across sessions

• Windows: Open Task Scheduler, create a task triggered at your desired interval, set the program to your Python executable (or launcher), add relay_runner.py --config relay_config.json --once as arguments, and set Start in to the extracted Relay directory. Test the task manually.
• macOS: Use a user launchd agent with ProgramArguments pointing to Python, the absolute path to relay_runner.py, --config, the absolute config path and --once. Set WorkingDirectory to the Relay folder and a suitable StartInterval; load the agent and inspect its logs.
• Linux: Use cron or a systemd timer. Example for a 15-minute cron schedule (replace both paths):

*/15 * * * * cd /ABSOLUTE/PATH/relay && /usr/bin/python3 relay_runner.py --config relay_config.json --once

Use an interval appropriate for the source and its terms of use. Do not launch overlapping runs of the same job. Relay has a single-instance lock for each output folder, but scheduling should still avoid unnecessary collisions.

Reset the baseline deliberately

python3 relay_runner.py --config relay_config.json --reset-baseline --once

This clears the stored baseline state and runs another check; previous event and run logs remain. Do not reset merely to force a duplicate event. On Windows use py -3 if required.

Where to look: runs.jsonl records successful checks, held decisions and errors; events.jsonl contains triggered events. The selected action creates notes/, events.csv or snapshots/ when appropriate. The Decision Lab history is separate and exists only in the browser session.

No account or hosted lock-in: Relay builds and simulates in the browser. The exported worker runs on your machine using Python 3.9+ standard libraries. There is no Relay cloud account, paid API requirement or automatic telemetry in the runner.

• Source permissions: Monitor only sources you may access. Respect site terms, robots guidance, copyright and sensible polling intervals. Markdown output contains source metadata and a short excerpt, not a licence to republish full articles.
• Data and credentials: Configurations and local outputs remain on your machine after export. Do not put credentials in source URLs or share configuration files containing private endpoints. Remote sources use HTTPS except for localhost testing.
• Technical limits: Sources are limited to 2 MB per response and RSS/Atom processing to 500 entries per check. HTML is read as returned text; JavaScript-rendered page content is not executed. A remote source may change format, disappear or reject automated requests.
• Webhook delivery: Optional HTTPS webhooks send event data to a receiver you control. Delivery is at-least-once; the receiver should deduplicate using X-Relay-Event-ID. The browser's Decision Lab never sends webhooks.
• Reliability: Relay records decisions and failures but does not guarantee uninterrupted monitoring, exactly-once delivery or detection of every intermediate state. Keep the computer online and inspect the run ledger periodically.