RELAY AGENT

Give your agents
a safe way in.

Relay sits between your AI agents and your database. Risky queries are blocked, sensitive data is masked and every query is audited.

Get started ↗

Claude Code · Codex · Cursor · psql · DBeaver
PostgreSQL · MySQL · MongoDB · SQL Server · Oracle · Valkey

  1. AI agent · psql · DBeaverSends SQL to 127.0.0.1, like any database
  2. relay CLISigned in as a person, with that person’s grants
  3. Relay AgentRuns in your network, next to the database
  4. Your databasePostgreSQL, MySQL, MongoDB, SQL Server, Oracle or Valkey / Redis
ai agent — 127.0.0.1:7000psql — 127.0.0.1:7001dbeaver — 127.0.0.1:7002relay-agent / policy: memberpassprod-dbyour networkrafael@example.comcredentials — never leavereq 1,204/s · simrows 3,612/s · simai agent — 127.0.0.1:7000psql — 127.0.0.1:7001dbeaver — 127.0.0.1:7002relay-agent / policy: memberpassprod-dbyour network

Fig. 00 — the wire

open — queries pass, responses return clean

HOW IT WORKS

One gate between the agent and your data.

The agent connects to a local port. The Relay Agent in your network checks, masks and records every statement.

  1. AI agent · psql · DBeaverSends SQL to 127.0.0.1, like any database
  2. relay CLISigned in as a person, with that person’s grants
  3. Relay AgentRuns in your network, next to the database
  4. Your databasePostgreSQL, MySQL, MongoDB, SQL Server, Oracle or Valkey / Redis

Enforced on every statement

  • MASKING

    Sensitive data stays out of the model’s context.

  • GUARDRAILS

    A DELETE without WHERE never runs.

  • APPROVALS

    Writes can wait for a person.

  • CREDENTIALS

    The model never holds a password.

  • ACCESS

    Access that ends on its own.

  • AUDIT

    Every query, tied to a person.

Bring your coding agent.

Install the Relay skill. Your agent signs in as you, connects through Relay and follows your rules.

Install the Relay skill

npx skills add relay-sh/skills

Run it in your project. Add -g to install for your user, or -a <agent> to pick the agent.

Ask your agent to set it up

Paste this into the agent. It installs the CLI, waits for you to sign in and lists your connections.

Set up Relay for this project.
1. If `relay` is not on PATH, install it: `brew install relay-sh/tap/relay` on macOS or Linux, `choco install relay` on Windows. Then run `relay version`.
2. Run `relay login` and wait while I finish signing in in the browser.
3. Run `relay whoami` and `relay connections list`, and tell me which connections I can use.
4. Follow the Relay skill at `relay/SKILL.md` from now on.
Do not connect to any database yet.
No skills CLI? Copy the files insteadSKILL.md, AGENTS.md, CLAUDE.md or Cursor rules
relay/SKILL.md42 lines
---
name: relay
description: Use when a task needs a database reached through Relay or the relay CLI, to install it, sign in, connect, read the audit log, and handle masked or denied results.
---

# Relay: database access for this project

Databases in this project are reached through Relay. The `relay` CLI opens a local tunnel to a Relay Agent; the agent applies column-level masking before data reaches you and can record each statement in an audit log. Treat what Relay returns as the answer.

## Install
- macOS / Linux (Homebrew): `brew install relay-sh/tap/relay`
- Linux / macOS (script): `curl -fsSL https://docs.userelay.sh/install.sh | bash`
- Windows: `choco install relay` or `irm https://docs.userelay.sh/install.ps1 | iex`
- Check the install: `relay version`

## Sign in
- `relay login` opens a browser for Google sign-in. A person finishes it; do not automate the browser step.
- Company SSO: `relay login --sso --email you@company.com`
- `relay whoami` prints the signed-in user, organization and token expiry.

## Connect
- `relay connections list` shows the connections this account can use.
- `relay connect prod-db` opens a local listener and prints its address. It stays in the foreground until Ctrl+C, so run it in its own terminal or background process.
- `relay connect prod-db --port 7000` pins the port; point the database client at `127.0.0.1:7000`.
- `relay status` lists what is running. Close with `relay disconnect prod-db` or `relay disconnect --all`.

## What Relay enforces
- Masked values are the real answer for this role. Do not try to recover, infer or reconstruct the originals.
- An action the role does not allow fails with: "permission denied — your role does not allow this action in this organization/workspace". That decision is final.
- "session expired or invalid — run 'relay login' to authenticate" means a person has to sign in again.

## Audit
- `relay audit-logs --connection prod-db --limit 20` lists recent events with TIME, CONNECTION, USER, DATABASE, TYPE, QUERY.
- Use it to show the user what ran on their behalf.

## Rules for agents
1. Reach databases only through `relay connect prod-db`. Never ask for, guess or use direct hosts, passwords or connection strings.
2. Never print, copy or commit tokens or `~/.userelay/profiles.json`.
3. Do not use `--insecure`, `--server`, `--server-http`, `RELAY_SERVER`, `RELAY_SERVER_HTTP`, `RELAY_INSECURE` unless the user asks for it.
4. Do not run admin commands (`relay connections create|update|delete`, `relay roles`, `relay bindings`, `relay members`, `relay db create|delete`) unless the user asks for that exact change.
5. Prefer read-only queries. Ask before any write, schema change or bulk export.
6. When Relay masks or denies something, tell the user and stop. Do not retry through another profile, organization, workspace or tool.
Agent brief, ready to pasteCommands from the public relay CLI and its Homebrew tap. prod-db is a placeholder.

Get started ↗Setup guide ↗Log in ↗