Self-hosting

Governance (relaygate)

The optional governance gate between agents and Relaycast and Sessions - groups, filesystem-style permissions, and a classifier on everything that crosses a boundary or leaves.

Agent version of this guide · Markdown

Optional, off by default. relaygate sits between your agents and Relaycast and Sessions. Use it when some agents may see regulated data and others must not: it keeps the two apart and decides what may leave.

Status: build 2. relaygate checks registration, permissions, Slack posts and knowledge-base writes, and proxies Relaycast (REST and the node WebSocket) and Sessions. It isolates agents only when they can reach Relaycast and Sessions through the gate alone: turn the proxies on and narrow Relaycast's and Sessions' own network policies to the gate (below), or keep regulated agents in their own install.

Sessions credentials bypass the gate through the public history host (history.<domain>) unless gate-only mode is on. Network policies don't stop this: the load balancer still reaches the read API and the ingest edge. See Gate-only.

Known gap: without gate-only, people signed in to the dashboard or the desktop app read Sessions directly, not through relaygate, so the group rules don't apply to them.

relaygate between agents, Relaycast and Slack

How it works

  1. Groups. An agent registers once, with an enrollment key. The key decides its group; the agent can't pick its own. Limit each key to a name prefix, so a leaked key can't create arbitrary agents or take another group's names.
  2. Permissions. Every channel, inbox, session and external stream (a Slack thread, a knowledge-base page) has an owner, a group and a mode, like a file: three digits for owner/group/other, each 4 (read) plus 2 (write). An access list adds access for named groups. A request the policy doesn't allow never reaches Relaycast or Sessions.
  3. Classifier. Writes that cross a group boundary, and anything leaving through Slack or a knowledge base, are classified first: rules (for example, US social security numbers, prompt injection) plus an optional Claude model with your guidance. A refusal is final; if the classifier can't decide, nothing is sent.
  4. Audit. Every decision, which stage made it and the policy version in force are logged. Message content is never logged.

The default policy has two groups:

WhoGroupMayMay not
Agents inside the boundary (Slack thread agents, server agents)22, pitread and write their streams and Slack threads; read outside sessionswrite into outside inboxes or sessions
Agents outside it (laptops, editors)11, localwrite into pit inboxes; read and write their own streamsread anything in the pit; post to Slack

The policy

The policy is one JSON document, rendered from the chart's policy values; relaygate reloads it when it changes and keeps the last good one if an edit is invalid. The chart's defaults follow relaygate's examples/policy.pit.json.

KeyWhat it sets
groupsEach gid and its name. relaygate has no built-in groups.
enrollmentKeysPer key: its id, gid, sha256 (never the key itself) and namePrefix.
streamDefaults, streamOverridesgid, mode, acl and classify per stream prefix (longest match wins), then for one stream. A stream no entry matches is refused.
sessionDefaults, sessionOverridesMode and acl for sessions by the first uploader's group, then for one session id (an override never changes the owning group).
ceilingsPer group, the groups it may never touch, whatever an ACL says.
classifierrules (regular expressions) and an optional model with guidance.

The chart's default streams are all 660 (owner and group) plus an explicit ACL for each cross-group grant:

StreamsOwner groupACL
relaycast:channel/, relaycast:inbox/local-11pit (22) may read
relaycast:channel/pit-, relaycast:inbox/pit-, relaycast:inbox/slack-22local (11) may write
relaycast:channel/slack (the Slack app's routing channel)22none
slack:, kb:22none; classified

Guests (another company's agents) get their own group, a key with guest: true and an expiresAt, and a ceiling such as { gid: 44, never: [22] }. Revoking or expiring a guest key ends every token issued from it. A deployment where laptops stay outside the regulated boundary and cloud agents work inside it is examples/policy.double-pit.json.

Test a draft before you apply it: relaygate-explain --policy draft.json --cases cases.json (npm run explain -- in a relaygate checkout) answers "may X do this, and why" without a running gate and exits 1 if any case fails.

Install

Generate one enrollment key per group, keep the keys in your secret store, and put only their sha256 in the policy:

for g in local pit bridge; do openssl rand -hex 32 > $g.key; printf '%s ' $g; tr -d '\n' < $g.key | shasum -a 256; done
# relaygate-values.yaml
image:
  digest: sha256:<published digest>
policy:
  enrollmentKeys:
    - { id: local, gid: 11, sha256: "<sha256 of local.key>", namePrefix: "local-" }
    - { id: pit, gid: 22, sha256: "<sha256 of pit.key>", namePrefix: "pit-" }
    - { id: slack-bridge, gid: 22, sha256: "<sha256 of bridge.key>", namePrefix: "slack-" }
  classifier:
    model: { enabled: true, model: claude-opus-5-5, effort: low, timeoutMs: 8000 }
secrets:
  anthropicApiKey: { name: relaygate-anthropic, key: api-key }   # only with the model classifier

The model classifier is off by default (rules only). Where regulated data may be classified, use a zero-data-retention Anthropic key. The chart refuses a sha256 that isn't 64 hex characters, so a raw key can't land in the policy.

The chart isn't in a published release yet, so install it from a checkout of the infra repository:

git clone --depth 1 https://github.com/AgentWorkforce/infra.git
helm upgrade --install relaygate ./infra/charts/relaygate -n agent-relay -f relaygate-values.yaml

Or, if you install the umbrella from the same checkout, set components.relaygate: true and put the same values under relaygate:. Its Service is then agent-relay-relaygate (<release>-relaygate in general; relaygate for a standalone release of that name). One replica: registrations and the audit log are SQLite on the gate's volume.

Done when: the relaygate pod's /readyz returns 200 with the policy_version you expect.

Proxy Relaycast and Sessions

# relaygate-values.yaml, in addition to the above
proxy:
  relaycastUrl: http://relaycast:8787
  sessionsUrl: https://history.example.com   # one origin for session reads and uploads
secrets:
  relaycastWorkspaceKey: { name: relaygate-relaycast, key: workspace-key }  # rk_live_ key the gate registers agents with
  relaygateSecret: { name: relaygate-seal, key: secret }                   # 32+ characters; keep it for the life of the volume
  adminToken: { name: relaygate-admin, key: token }                        # optional, see Operate
  • Relaycast. The gate forwards an allowlist of REST routes and the realtime path (/v1/agent/node-token, then the /v1/node/ws WebSocket), filtering reads, lists, search and live deliveries to what the caller may read. Agents hold an rg_ token and never the workspace key.
  • Sessions are served at /sessions. The gate holds no Sessions token: a caller sends its rg_ token in X-Relaygate-Token and its own Sessions credential in Authorization, which the gate checks against the policy and forwards unchanged. secrets.sessionsToken (an rth_st_ service token with rth:sync and rth:read) is optional, only for callers that send no Sessions credential.
  • proxy.sessionsUploadUrl and proxy.sessionsReadUrl send uploads and reads to separate upstreams (each defaults to sessionsUrl). proxy.sessionsHosts serves listed hosts at the root, so you can point the history origin itself at the gate; then both split upstreams are required, and the chart refuses a listed host as an upstream so requests can't loop back to the gate.

Then close the direct path. NetworkPolicies are additive: a separate policy that admits only the gate does nothing while Relaycast's own policy admits the whole namespace (its default). Narrow Relaycast's policy instead, in the relaycast values (relaycast: in the umbrella):

networkPolicy:
  enabled: true
  ingressFrom:
    - podSelector: { matchLabels: { app.kubernetes.io/name: relaygate } }
    # plus every caller that must stay direct (relay-control, the ingress
    # controller if Relaycast is exposed, ...); anything not listed is cut off

Restrict Sessions to the gate the same way. Callers hold real Sessions credentials, so the gate is only as strong as that rule. With relaygate's Sessions proxy, add the relaygate pods to sessions-pipeline.sessionReadApi.networkPolicy.publicFrom and to the ingest NetworkPolicy (sessions-pipeline.ingestEdge.networkPolicy.ingressFrom), or relaygate's Sessions reads time out. The downloadable GKE values.yaml lets every pod in the install namespace reach the ingest edge: replace that namespaceSelector entry with relaygate and the callers that must stay direct, keeping the load balancer's ranges. On GKE, the cluster must enforce network policies: see step 2 of Install on GKE.

Done when: an agent with an rg_ token reaches Relaycast through the gate, a Slack-app agent registers into the pit through the gate and replies in its thread, and from an agent's pod both a direct request to Relaycast and a direct upload to the ingest edge are refused.

Gate-only

Narrowing the network policies closes the in-cluster paths only. Anyone holding a Sessions credential (an agent, or a workspace member who mints a read token) can still read and upload at https://history.<domain>, and call Relaycast at cast.<domain>, without going through relaygate.

Gate-only mode closes those routes. It needs agent-relay chart 0.7.36 or later (infra#384, #396) and is off by default:

global:
  relaygate:
    gateOnly:
      enabled: true

With it on:

  • history.<domain> and cast.<domain> route only relaygate's paths, to relaygate; everything else is denied at the edge;
  • the Sessions read API and the ingest edge admit only relaygate;
  • Control reads Sessions through relaygate's internal port 8081, and the dashboard and the desktop app reach Sessions through relaygate, so the group rules apply to signed-in people too.

Helm refuses to render gate-only while a required value is missing. The values, prerequisites (a relaygate image that maps Control users to groups, and policy.controlPrincipals rules) and the full list of changes are in infra's docs/self-hosted-relaygate.md.

Done when: with gate-only on, a workspace member's own Sessions read token used at https://history.<domain>/v1/sessions/<id>/events, for a session their group may not read, is refused, and from an agent's pod a direct request to the read API or the ingest edge is refused.

Point clients at it

Each client registers once with its group's enrollment key (POST /v1/register) and gets an rg_ token. Then:

  • Relaycast: set its base URL to the gate and use the rg_ token in place of any Relaycast credential. API paths are unchanged.
  • Sessions: set its base URL to https://<gate>/sessions (or keep the history origin, with proxy.sessionsHosts), send the rg_ token in X-Relaygate-Token, and keep its own Sessions credential in Authorization.

The Slack app takes relaygate.url and the bridge key: it registers through the gate, uses it as its Relaycast address, and every Slack post is checked before it is sent.

Operate

With secrets.adminToken set, the gate also serves:

  • POST /admin/v1/explain: "may X do this operation on this stream or session, and why", against the live policy or a draft. It never calls the classifier or changes anything.
  • GET /admin/v1/audit?after=<seq>&agent=<name>&limit=<n>: decision rows, oldest first, each with its policy_version.

Reference: docs/self-hosted-relaygate.md and the relaygate contract.


Stuck? See troubleshooting or support.