arelay

# Agent Relay

[![CI](https://github.com/mmmikael/arelay/actions/workflows/ci.yml/badge.svg)](https://github.com/mmmikael/arelay/actions/workflows/ci.yml)
[![CodeQL](https://github.com/mmmikael/arelay/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mmmikael/arelay/actions/workflows/github-code-scanning/codeql)
[![License: MIT](https://img.shields.io/github/license/mmmikael/arelay)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Svelte](https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev/)
[![Website](https://img.shields.io/badge/website-arelay.app-blue)](https://arelay.app)

Agent Relay is an open-source, end-to-end encrypted inbox for AI agents. Anything that can
make HTTP requests can deliver — Cursor, Codex, Claude Code, cron jobs, webhooks, or your
own backend. Agents deliver files, reports, HTML, Markdown, PDFs, and images through a
small HTTP API; you review them in a private web inbox with preview, download, and
read/unread state.

![An encrypted delivery arriving in the Agent Relay inbox and the report opening in the preview pane](docs/demo.gif)

An optional **Email Review Relay** plugin adds a human-in-the-loop outbound email path: agents submit
encrypted drafts, you preview them in the same inbox, then approve or reject before anything
is sent. It is enabled on [arelay.app](https://arelay.app); self-hosters can turn it on with
`EMAIL_REVIEW_RELAY_ENABLED=true` ([setup](#email-review-relay)).

**Two ways to use it:**

- **[arelay.app](https://arelay.app)** — hosted service; sign up and connect your agents
  (no deployment).
- **Self-host** — run this repo on your own infrastructure under the MIT license.

## Contents

### Using [arelay.app](https://arelay.app)

- [Get started](#get-started)
- [Connect your AI agent](#connect-your-ai-agent)
- [Encryption (required)](#encryption-required)
- [Email Review Relay](#email-review-relay)
- [Features](#features)

### Self-hosting

- [Development setup](#development-setup)
- [Environment variables](#environment-variables)
- [Deploy to production](#deploy-to-production)
- [Plugins](#plugins)
- [Tech stack](#tech-stack)

### Reference

- [Contributing & help wanted](#contributing--help-wanted)
- [Security model](#security-model)
- [Terms of Service](https://arelay.app/terms) · [Privacy Policy](https://arelay.app/privacy)
- [Contributing](./CONTRIBUTING.md)
- [License](#license)

---

## Using [arelay.app](https://arelay.app)

The hosted service at [arelay.app](https://arelay.app) handles deployment, database,
storage, backups, TLS, and updates. The security model is the same as self-hosting:
encrypted deliveries are decrypted in your browser, not on the server.

### Get started

1. Open **[arelay.app](https://arelay.app)** and create an account with a passkey.
2. Accept the [Terms of Service](https://arelay.app/terms) and
   [Privacy Policy](https://arelay.app/privacy) during signup (required on the hosted
   service).
3. Complete **Set up encryption** on first portal visit (passkey + recovery key).
4. In the portal, open **Account → Agent tokens** and create a named token for each agent
   or integration.
5. Copy the token once — it is shown only at creation time.
6. Your inbox updates automatically when agents send deliveries (refresh every few seconds).

Sign-in uses passkeys (WebAuthn), not passwords or social login. No Google, Apple, or
Microsoft account is required. If terms or privacy are updated later, existing accounts are
prompted to accept the new versions before continuing.

### Connect your AI agent

Agent Relay is agent-agnostic: any client that speaks HTTP and follows the
[E2EE envelope format](#encryption-required) can deliver. Pick the path that fits your setup:

| Integration path | Best for |
| --- | --- |
| [CLI & MCP server](#cli--mcp-server) | Fastest start: one command from any shell, or native MCP tools in Claude Code, Cursor, and Claude Desktop |
| [Agent skill](#agent-skill) | Cursor, Codex, Claude Code, Hermes Agent, and other [Agent Skills](https://agentskills.io/specification) hosts |
| [Direct HTTP API](#direct-http-api) | Custom scripts, backends, webhooks, scheduled jobs |
| [Platform plugins](#platform-plugins) | Platform-specific hooks, e.g. Hermes cron delivery |

Whichever path you choose, set these where your agent runs — **never commit tokens**:

| Variable | Value for [arelay.app](https://arelay.app) |
| --- | --- |
| `ARELAY_URL` | `https://arelay.app` |
| `ARELAY_TOKEN` | Token from Account → Agent tokens |

Every request uses `Authorization: Bearer <ARELAY_TOKEN>`.

#### CLI & MCP server

The [`@arelay/cli`](./packages/arelay) npm package wraps the API and all envelope encryption.
Deliver from any shell:

```bash
export ARELAY_TOKEN=ar_...   # from Account → Agent tokens
npx -y @arelay/cli send report.md --title "Q2 revenue report"
```

Or register it as an MCP server so agents can deliver work natively
(`deliver_to_inbox`, `list_inbox_sessions`, `submit_email_draft` tools):

```bash
# Claude Code
claude mcp add arelay --env ARELAY_TOKEN=ar_... -- npx -y @arelay/cli mcp
```

`npx -y @arelay/cli check` verifies the token and encryption setup. The package also exports a
typed SDK (`import { ArelayClient } from '@arelay/cli'`) — see its
[README](./packages/arelay/README.md). Self-hosters point it at their deployment with
`ARELAY_URL`.

#### Agent skill

Install the [`agent-relay`](https://github.com/mmmikael/arelay-skills/tree/main/skills/agent-relay) skill (requires
[portal E2EE setup](#encryption-required)):

```bash
npx skills add mmmikael/arelay-skills --skill agent-relay -g -y
```

Hermes Agent:

```bash
hermes skills tap add mmmikael/arelay-skills
hermes skills install mmmikael/arelay-skills/agent-relay
```

#### Direct HTTP API

Anything that can POST JSON can deliver: fetch the public key from
`GET /api/agent/e2ee/config`, encrypt locally, create a session, and upload artifacts. See
the [API reference](https://github.com/mmmikael/arelay-skills/blob/main/skills/agent-relay/references/api-reference.md)
and the bundled Node reference scripts in the skill for working encryption code.

#### Platform plugins

**Hermes cron** (`--deliver arelay`) needs [arelay-hermes-plugin](https://github.com/mmmikael/arelay-hermes-plugin).
Cron runs in the **gateway**, not the interactive CLI — put credentials in
`~/.hermes/.env` (including `AGENT_RELAY_HOME_CHANNEL=https://arelay.app`), install the
plugin, then restart the gateway:

```bash
hermes plugins install mmmikael/arelay-hermes-plugin --enable
# ~/.hermes/.env: AGENT_API_TOKEN, AGENT_RELAY_URL, AGENT_RELAY_HOME_CHANNEL
#   (the Hermes plugin reads its own variables, not the CLI's ARELAY_* ones)
hermes gateway start
/cron add "0 9 * * *" "Your prompt. Never use [SILENT]." --deliver arelay
```

### Encryption (required)

All agent deliveries must be end-to-end encrypted. Complete **Set up encryption** during
[Get started](#get-started); unlock in the browser when viewing the inbox. Agents fetch your
public key from `GET /api/agent/e2ee/config` and upload encrypted sessions and artifacts.
Plaintext agent payloads return `400` (`plaintext_not_allowed`); unconfigured accounts get
`428` (`e2ee_required`).

### Email Review Relay

On [arelay.app](https://arelay.app), agents POST encrypted email drafts; each appears as an
inbox session you **Approve** (send via your Cloudflare credentials) or **Reject**.

1. **Account → Email sending (Cloudflare API)** — save your Cloudflare Account ID and API
   token (encrypted server-side; used only when you approve).
2. Use the **agent-relay** skill — drafts use the same E2EE envelopes as file deliveries.

API details and self-host setup: [Plugins](#plugins).

### Features

- Mobile-friendly email-style inbox
- Email Review Relay: agents draft outbound mail; you approve before send
- Artifact preview and download (text, Markdown, HTML, PDF, images)
- Sandboxed HTML/Markdown preview (external links and media stripped)
- End-to-end encrypted deliveries only
- Passkey sign-in (one passkey per account)
- Named agent API tokens with per-token revoke
- Storage limits: 25 MB per artifact, 500 MB per account

---

## Self-hosting

Run Agent Relay on your own PostgreSQL and S3-compatible storage. Useful when you need full
data residency control or a private deployment.

### Development setup

```bash
npm install
cp .env.example .env
npm run db:migrate:local
npm run dev
```

Open [http://127.0.0.1:5173](http://127.0.0.1:5173) and create an account with a passkey.
Without Cloudflare or SMTP configured, verification codes are printed to the server
console.

Database schema changes are managed with Drizzle migrations. Edit the Drizzle schema,
generate a migration with `npm run db:generate`, review the generated SQL, then apply it
with `npm run db:migrate:local`.

Run unit tests:

```bash
npm test
```

To test migrations against a disposable empty database, set `TEST_DATABASE_URL` and run:

```bash
npm run db:smoke
```

### Environment variables

| Variable | Description |
| --- | --- |
| `SESSION_SECRET` | Secret for signing human session cookies. Generate with `openssl rand -hex 32`. |
| `SESSION_VERSION` | Bump this to invalidate existing human sessions. |
| `ORIGIN` | Public site URL for CSRF checks and absolute links. In production, set to your canonical URL, for example `https://arelay.app`. |
| `WEBAUTHN_RP_NAME` | Passkey relying party display name. Defaults to `Agent Relay`. |
| `WEBAUTHN_RP_ID` | Passkey relying party ID. For production on arelay.app, use `arelay.app`. |
| `WEBAUTHN_ORIGIN` | Expected passkey origin, for example `https://arelay.app`. |
| `DATABASE_URL` | PostgreSQL connection string. |
| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare account ID for [Email Sending](https://