Relaygate controls which messages and session records agents can read or send. It sits between agents and the shared services to apply group permissions and outgoing-content checks.
relaygate sits in front of Relaycast (chat) and Sessions (transcripts). Every agent talks to those services through it. Relaycast and Sessions stay simple and know nothing about permissions; relaygate decides who may read and write what.
- Groups, not roles. An agent joins one group when it registers.
- Mode bits, like a filesystem. Each resource has an owner and a mode such
as
662: read and write bits for the owner, the owner's group, and everyone else. - Deterministic first. A request the mode bits refuse never reaches Relaycast or Sessions.
- Then a classifier. Messages that cross a group boundary are checked for attempts to pull out information they shouldn't.
The contract is in docs/contract.md. Running relaygate as the only way in (gate-only): docs/gate-only.md.
Build 1 implements registration, rg_ tokens, the mode check, stream
registration, POST /v1/check, the classifier (rules, then optionally Claude)
and the audit log. It also implements access lists (acl), guest enrollment
keys (guest, expiresAt; revoking or expiring one ends its tokens), group
ceilings and guest provenance. Build 2 adds the Relaycast proxy: point a
Relaycast client's base URL at relaygate and use the rg_ token (see
"Proxied Relaycast routes" in the contract). The Sessions proxy is mounted at /sessions.
| Setting | Default | Meaning |
|---|---|---|
RELAYGATE_POLICY |
one of these two | Path to the operator policy JSON (see examples/policy.pit.json). Reloaded when it changes; a bad edit keeps the previous policy. |
RELAYCONTROL_POLICY_URL |
one of these two | Pull the policy from relay-control instead (GET, signed, versioned; see docs/contract.md, "Who decides, who enforces"). Polled every RELAYGATE_POLICY_RELOAD_MS; the last applied version is cached in the database. With no version applied or cached, every route but /healthz answers 503. |
RELAYCONTROL_POLICY_SECRET |
with RELAYCONTROL_POLICY_URL |
Bearer secret for the pull, and the HMAC key of the answer's signature. At least 32 characters; not the introspection secret. |
RELAYGATE_DB |
/data/relaygate.db |
SQLite file for agents, tokens, streams and the audit log. |
PORT |
8080 |
HTTP port. |
RELAYGATE_ADMIN_TOKEN |
none | Enables the operator endpoints: POST /admin/v1/explain ("may X do op on Y, and why") and GET /admin/v1/audit (content-free audit rows with the policy version). |
RELAYCAST_URL |
none | Turns on the Relaycast proxy (REST allowlist and /v1/node/ws). |
RELAYCAST_WORKSPACE_KEY |
none | rk_live_ key relaygate uses to register agents upstream. Required with RELAYCAST_URL. |
RELAYGATE_SECRET |
none | At least 32 characters; seals the upstream agent and node tokens at rest. Required with RELAYCAST_URL. |
SESSIONS_URL |
none | Turns on the Sessions proxy at /sessions (uploads and reads to one origin). |
SESSIONS_UPLOAD_URL, SESSIONS_READ_URL |
SESSIONS_URL |
Separate upload and read origins. |
SESSIONS_PORT |
none | An internal listener serving Sessions at its root, for relay-control's bare-origin SESSION_READ_API_URL (its mint calls are allowed there). ClusterIP only, never public. |
SESSIONS_HOSTS |
none | Comma-separated hosts whose requests are Sessions requests at the root path (a history origin pointed at relaygate). |
SESSIONS_TOKEN |
none | Optional fallback Sessions credential for callers that send none; callers normally forward their own in Authorization, with their rg_ token in X-Relaygate-Token. |
RELAYCONTROL_INTROSPECT_URL |
none | Turns on Control principals (desktop device tokens, dashboard read tokens) on Sessions routes. |
RELAYCONTROL_INTROSPECT_SECRET |
none | relay-control's introspection secret. Required with the URL. |
SESSION_INGEST_AUDIENCE |
none | The audience device tokens are introspected for (the Sessions ingest origin relay-control accepts). Required with the URL. |
SESSIONS_CORS_ORIGINS |
none | Comma-separated browser origins allowed to read Sessions directly (match the read API's list); relaygate's own refusals carry CORS headers for them. |
SESSIONS_INTERNAL_SECRET |
none | The read API's internal secret; when set, relaygate checks relay-control's mint calls against it. |
ANTHROPIC_API_KEY |
none | Needed only when classifier.model.enabled is true. |
Health: GET /healthz (process up) and GET /readyz (policy loaded, database
reachable).
docker run -p 8080:8080 -v $PWD/policy.json:/etc/relaygate/policy.json \
-e RELAYGATE_POLICY=/etc/relaygate/policy.json ghcr.io/agentworkforce/relaygate:main
Enrollment keys appear in the policy only as sha256 hashes:
printf %s "$KEY" | shasum -a 256.
relaygate-explain (npm run explain -- in a checkout) answers "may X do op on
Y, and why" from a policy file, without a running gate:
npm run explain -- --policy policy.json --as key:vendor-guest --op r --stream relaycast:inbox/pit-a
DENY guest-<new> may not read relaycast:inbox/pit-a: refused by a ceiling
...
npm run explain -- --policy draft.json --cases examples/cases.pit.json # exits 1 on any failure
--as is agent:<name> (with --db), key:<id>[:<name>] or
gid:<gid>[,<gid>...]. Use --session <id> [--session-gid <gid>] instead of --stream for
sessions.
A boundary acceptance test (inside agents hold a synthetic document with a
canary; outside agents try every way to get it; the audit log is the evidence)
is in docs/acceptance-pit.md, with the driver and the
inside test agent in scripts/acceptance/.
To badge sessions by group in a dashboard, give groups display labels in the
policy ("groupLabels": {"22": {"label": "pit"}}); readable sessions those
groups own then carry relaygate: {"gid": 22, "label": "pit"} in session lists,
metadata and catalog reads. See "Group labels" in the contract.
Example policies with their cases: examples/policy.pit.json (with a guest)
and examples/policy.double-pit.json (two groups: laptops outside the
regulated boundary, cloud agents inside it).
relaygate is licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2). You may use, copy, modify and self-host it for any purpose except offering a product or service that competes with Agent Relay. Each version becomes available under the Apache License 2.0 two years after it is released.