Developers keep working in Cursor or Claude Code while Relay accumulates events locally. relay sync pushes those captures to the Relay API for Architect and automation.
What gets uploaded
By default, sync discovers nested auto-collect files:
~/.relay/captures/<agentId>/<sessionId>.json--from hook-events is an explicit override for the legacy hook-events.jsonl log. --from watch is an alias for auto-collect (~/.relay/captures/<agent>/<session>.json written by relay watch).
Basic sync workflow
# After one or more agent tasks
relay syncSuccessful output includes the number of events uploaded and the target environment (dev API: https://api.dev.relay.oprag.ai).
Growing auto-collect captures stay on one server session: each relay sync appends only new turns and leaves the session open. Close it when the task is done:
relay sync --finalize--from file and --from hook-events still create, upload, and complete in one shot.
Automate on a schedule
For teams that prefer periodic uploads instead of manual sync:
relay sync --dry-run # inspect pending events first
relay syncAdd relay sync to CI or a cron job only on machines that already run hooks — never from shared servers without local captures.
Query sessions from the API
After sync, session IDs are available in Architect. For programmatic checks, use the Relay API contract in relay/packages/api-contract (session list and detail routes ship with the MVP skeleton).
Example health check:
curl -s https://api.dev.relay.oprag.ai/healthAuthenticated session routes require the same credentials you configure with relay auth.
Troubleshooting
| Symptom | Fix |
|---|---|
401 on sync | Run relay auth and confirm relay status shows a token |
| Empty upload | Confirm nested ~/.relay/captures/<agentId>/<sessionId>.json files exist after tasks |
| Duplicate sessions | Growing auto-collect should re-sync the same file; use --finalize once, not a new --from file each time |