{
  "markdown": "# Agent Relay\n\n[![CI](https://github.com/mmmikael/arelay/actions/workflows/ci.yml/badge.svg)](https://github.com/mmmikael/arelay/actions/workflows/ci.yml)\n[![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)\n[![License: MIT](https://img.shields.io/github/license/mmmikael/arelay)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![Svelte](https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev/)\n[![Website](https://img.shields.io/badge/website-arelay.app-blue)](https://arelay.app)\n\nAgent Relay is where your AI agents ask permission. Agents draft emails, request spend, and\ndeliver finished work into a private, end-to-end encrypted inbox; nothing leaves, sends, or\ncharges until you approve it. Anything that can make HTTP requests can use it — Cursor,\nCodex, Claude Code, cron jobs, webhooks, or your own backend — and it is open source under\nMIT, so you can run it yourself.\n\n![An encrypted delivery arriving in the Agent Relay inbox and the report opening in the preview pane](docs/demo.gif)\n\nAn optional **Email Review Relay** plugin adds a human-in-the-loop outbound email path: agents submit\nencrypted drafts, you preview them in the same inbox, then approve or reject before anything\nis sent. It is enabled on [arelay.app](https://arelay.app); self-hosters can turn it on with\n`EMAIL_REVIEW_RELAY_ENABLED=true` ([setup](#email-review-relay)).\n\n**Two ways to use it:**\n\n- **[arelay.app](https://arelay.app)** — hosted service; sign up and connect your agents\n  (no deployment).\n- **Self-host** — run this repo on your own infrastructure under the MIT license.\n\n## Contents\n\n### Using [arelay.app](https://arelay.app)\n\n- [Get started](#get-started)\n- [Connect your AI agent](#connect-your-ai-agent)\n- [Encryption (required)](#encryption-required)\n- [Email Review Relay](#email-review-relay)\n- [Features](#features)\n\n### Self-hosting\n\n- [Development setup](#development-setup)\n- [Environment variables](#environment-variables)\n- [Deploy to production](#deploy-to-production)\n- [Plugins](#plugins)\n- [Tech stack](#tech-stack)\n\n### Reference\n\n- [Contributing & help wanted](#contributing--help-wanted)\n- [Security model](#security-model)\n- [Terms of Service](https://arelay.app/terms) · [Privacy Policy](https://arelay.app/privacy)\n- [Contributing](./CONTRIBUTING.md)\n- [License](#license)\n\n---\n\n## Using [arelay.app](https://arelay.app)\n\nThe hosted service at [arelay.app](https://arelay.app) handles deployment, database,\nstorage, backups, TLS, and updates. The security model is the same as self-hosting:\nencrypted deliveries are decrypted in your browser, not on the server. The one exception is\napproving an email draft: the decrypted email is sent to the server in that request so it can\nbe delivered, and is never stored as plaintext. Email itself is not end-to-end encrypted, so\nthe recipient's mail provider sees the same content permanently.\n\n### Get started\n\n1. Open **[arelay.app](https://arelay.app)** and create an account with a passkey.\n2. Accept the [Terms of Service](https://arelay.app/terms) and\n   [Privacy Policy](https://arelay.app/privacy) during signup (required on the hosted\n   service).\n3. Complete **Set up encryption** on first portal visit (passkey + recovery key).\n4. In the portal, open **Account → Agent tokens** and create a named token for each agent\n   or integration.\n5. Copy the token once — it is shown only at creation time.\n6. Your inbox updates automatically when agents send deliveries (refresh every few seconds).\n\nSign-in uses passkeys (WebAuthn), not passwords or social login. No Google, Apple, or\nMicrosoft account is required. If terms or privacy are updated later, existing accounts are\nprompted to accept the new versions before continuing.\n\n### Connect your AI agent\n\nAgent Relay is agent-agnostic: any client that speaks HTTP and follows the\n[E2EE envelope format](#encryption-required) can deliver. Pick the path that fits your setup:\n\n| Integration path                      | Best for                                                                                                       |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| [CLI & MCP server](#cli--mcp-server)  | Fastest start: one command from any shell, or native MCP tools in Claude Code, Cursor, and Claude Desktop      |\n| [Agent skill](#agent-skill)           | Cursor, Codex, Claude Code, Hermes Agent, and other [Agent Skills](https://agentskills.io/specification) hosts |\n| [Direct HTTP API](#direct-http-api)   | Custom scripts, backends, webhooks, scheduled jobs                                                             |\n| [Platform plugins](#platform-plugins) | Platform-specific hooks, e.g. Hermes cron delivery                                                             |\n\nWhichever path you choose, set these where your agent runs — **never commit tokens**:\n\n| Variable       | Value for [arelay.app](https://arelay.app) |\n| -------------- | ------------------------------------------ |\n| `ARELAY_URL`   | `https://arelay.app`                       |\n| `ARELAY_TOKEN` | Token from Account → Agent tokens          |\n\nEvery request uses `Authorization: Bearer <ARELAY_TOKEN>`.\n\n#### CLI & MCP server\n\nThe [`@arelay/cli`](./packages/arelay) npm package wraps the API and all envelope encryption.\nDeliver from any shell:\n\n```bash\nexport ARELAY_TOKEN=ar_...   # from Account → Agent tokens\nnpx -y @arelay/cli send report.md --title \"Q2 revenue report\"\n```\n\nOr register it as an MCP server so agents can deliver work natively\n(`deliver_to_inbox`, `list_inbox_sessions`, `submit_email_draft` tools):\n\n```bash\n# Claude Code\nclaude mcp add arelay --env ARELAY_TOKEN=ar_... -- npx -y @arelay/cli mcp\n```\n\n`npx -y @arelay/cli check` verifies the token and encryption setup. The package also exports a\ntyped SDK (`import { ArelayClient } from '@arelay/cli'`) — see its\n[README](./packages/arelay/README.md). Self-hosters point it at their deployment with\n`ARELAY_URL`.\n\n#### Agent skill\n\nInstall the [`agent-relay`](https://github.com/mmmikael/arelay-skills/tree/main/skills/agent-relay) skill (requires\n[portal E2EE setup](#encryption-required)):\n\n```bash\nnpx skills add mmmikael/arelay-skills --skill agent-relay -g -y\n```\n\nHermes Agent:\n\n```bash\nhermes skills tap add mmmikael/arelay-skills\nhermes skills install mmmikael/arelay-skills/agent-relay\n```\n\n#### Direct HTTP API\n\nAnything that can POST JSON can deliver: fetch the public key from\n`GET /api/agent/e2ee/config`, encrypt locally, create a session, and upload artifacts. See\nthe [API reference](https://github.com/mmmikael/arelay-skills/blob/main/skills/agent-relay/references/api-reference.md)\nand the bundled Node reference scripts in the skill for working encryption code.\n\n#### Platform plugins\n\n**Hermes cron** (`--deliver arelay`) needs [arelay-hermes-plugin](https://github.com/mmmikael/arelay-hermes-plugin).\nCron runs in the **gateway**, not the interactive CLI — put credentials in\n`~/.hermes/.env` (including `AGENT_RELAY_HOME_CHANNEL=https://arelay.app`), install the\nplugin, then restart the gateway:\n\n```bash\nhermes plugins install mmmikael/arelay-hermes-plugin --enable\n# ~/.hermes/.env: AGENT_API_TOKEN, AGENT_RELAY_URL, AGENT_RELAY_HOME_CHANNEL\n#   (the Hermes plugin reads its own variables, not the CLI's ARELAY_* ones)\nhermes gateway start\n/cron add \"0 9 * * *\" \"Your prompt. Never use [SILENT].\" --deliver arelay\n```\n\n### Encryption (required)\n\nAll agent deliveries must be end-to-end encrypted. Complete **Set up encryption** during\n[Get started](#get-started); unlock in the browser when viewing the inbox. Agents fetch your\npublic key from `GET /api/agent/e2ee/config` and upload encrypted sessions and artifacts.\nPlaintext agent payloads return `400` (`plaintext_not_allowed`); unconfigured accounts get\n`428` (`e2ee_required`).\n\n### Email Review Relay\n\nOn [arelay.app](https://arelay.app), agents POST encrypted email drafts; each appears as an\ninbox session you **Approve** (send via your Cloudflare credentials) or **Reject**.\n\n1. **Account → Email sending (Cloudflare API)** — save your Cloudflare Account ID and API\n   token (encrypted server-side; used only when you approve).\n2. Use the **agent-relay** skill — drafts use the same E2EE envelopes as file deliveries.\n\nAPI details and self-host setup: [Plugins](#plugins).\n\n### Features\n\n- Mobile-friendly email-style inbox\n- Email Review Relay: agents draft outbound mail; you approve before send\n- Artifact preview and download (text, Markdown, HTML, PDF, images)\n- Sandboxed HTML/Markdown preview (external links and media stripped)\n- End-to-end encrypted deliveries only\n- Passkey sign-in (one passkey per account)\n- Named agent API tokens with per-token revoke\n- Storage limits: 25 MB per artifact, 500 MB per account\n\n---\n\n## Self-hosting\n\nRun Agent Relay on your own PostgreSQL and S3-compatible storage. Useful when you need full\ndata residency control or a private deployment.\n\n### Development setup\n\n```bash\nnpm install\ncp .env.example .env\nnpm run db:migrate:local\nnpm run dev\n```\n\nOpen [http://127.0.0.1:5173](http://127.0.0.1:5173) and create an account with a passkey.\nWithout Cloudflare or SMTP configured, verification codes are printed to the server\nconsole.\n\nDatabase schema changes are managed with Drizzle migrations. Edit the Drizzle schema,\ngenerate a migration with `npm run db:generate`, review the generated SQL, then apply it\nwith `npm run db:migrate:local`.\n\nRun unit tests:\n\n```bash\nnpm test\n```\n\nTo test migrations against a disposable empty database, set `TEST_DATABASE_URL` and run:\n\n```bash\nnpm run db:smoke\n```\n\n### Environment variables\n\n| Variable                     | Description                                                                                                                                                                                               |\n| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `SESSION_SECRET`             | Secret for signing human session cookies. Generate with `openssl rand -hex 32`.                                                                                                                           |\n| `SESSION_VERSION`            | Bump this to invalidate existing human sessions.                                                                                                                                                          |\n| `ORIGIN`                     | Public site URL for CSRF checks and absolute links. In production, set to your canonical URL, for example `https://arelay.app`.                                                                           |\n| `WEBAUTHN_RP_NAME`           | Passkey relying party display name. Defaults to `Agent Relay`.                                                                                                                                            |\n| `WEBAUTHN_RP_ID`             | Passkey relying party ID. For production on arelay.app, use `arelay.app`.                                                                                                                                 |\n| `WEBAUTHN_ORIGIN`            | Expected passkey origin, for example `https://arelay.app`.                                                                                                                                                |\n| `DATABASE_URL`               | PostgreSQL connection string.                                                                                                                                                                             |\n| `CLOUDFLARE_ACCOUNT_ID`      | Cloudflare account ID for [Email Sending](https://developers.cloudflare.com/email-service/). Use when your sending domain is on Cloudflare DNS.                                                           |\n| `CLOUDFLARE_API_TOKEN`       | Cloudflare API token with Email Sending permission.                                                                                                                                                       |\n| `EMAIL_FROM`                 | Required when Cloudflare or SMTP is configured. Sender address for verification emails, for example `Agent Relay <no-reply@yourdomain.com>`.                                                              |\n| `SMTP_HOST`                  | SMTP host for account email verification. Used when Cloudflare Email Sending is not configured.                                                                                                           |\n| `SMTP_PORT`                  | SMTP port. Defaults to `587`, or `465` when `SMTP_SECURE=true`.                                                                                                                                           |\n| `SMTP_SECURE`                | Set to `true` for implicit TLS SMTP.                                                                                                                                                                      |\n| `SMTP_USER`                  | SMTP username, if your provider requires authentication.                                                                                                                                                  |\n| `SMTP_PASSWORD`              | SMTP password, if your provider requires authentication.                                                                                                                                                  |\n| `S3_ENDPOINT`                | S3-compatible endpoint URL.                                                                                                                                                                               |\n| `S3_BUCKET`                  | S3 bucket name.                                                                                                                                                                                           |\n| `S3_PREFIX`                  | Object key prefix. Defaults to `agent-relay`.                                                                                                                                                             |\n| `S3_ACCESS_KEY`              | S3 access key.                                                                                                                                                                                            |\n| `S3_SECRET_KEY`              | S3 secret key.                                                                                                                                                                                            |\n| `S3_REGION`                  | S3 region. Defaults to `us-east-1`.                                                                                                                                                                       |\n| `PORT`                       | HTTP port for `npm start`. Defaults to `3000`. Railway sets this automatically.                                                                                                                           |\n| `BODY_SIZE_LIMIT`            | Max HTTP request body size for adapter-node. Required for encrypted artifact uploads (a 25 MB file needs ~37 MB of JSON; the Pro plan's 100 MB needs ~140 MB). Defaults to `140M` when using `npm start`. |\n| `NODE_ENV`                   | Set to `production` in production so session and WebAuthn cookies use `Secure`.                                                                                                                           |\n| `EMAIL_REVIEW_RELAY_ENABLED` | Optional plugin. Set to `true` to enable Email Review Relay (off by default).                                                                                                                             |\n\nWhen both Cloudflare Email Sending and SMTP are configured, Cloudflare is used.\n\n### Deploy to production\n\n**Requirements:**\n\n- PostgreSQL\n- S3-compatible object storage (see `scripts/iam-agent-relay-s3-policy.json` for a minimal\n  AWS IAM policy scoped to the `agent-relay/` prefix)\n- Email delivery for account verification ([Cloudflare Email Sending](https://developers.cloudflare.com/email-service/) or SMTP)\n- A stable HTTPS origin with correct WebAuthn RP settings\n\n**Build and run:**\n\n```bash\nnpm run db:migrate:local\nnpm run build\nnpm start\n```\n\nFor a fresh production database, run migrations before starting the app. If you are moving\nearly account/auth records from an old database, copy only `users`, `webauthn_credentials`,\n`e2ee_config`, and `agent_api_tokens`; leave inbox/content/plugin tables empty.\n\n**Railway:**\n\n1. Create a new service from [github.com/mmmikael/arelay](https://github.com/mmmikael/arelay).\n2. Add PostgreSQL and link `DATABASE_URL`.\n3. Add S3-compatible storage credentials.\n4. Set `SESSION_SECRET`.\n5. Set `WEBAUTHN_RP_ID` and `WEBAUTHN_ORIGIN` for your domain.\n6. Configure email delivery: Cloudflare Email Sending (`CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`, `EMAIL_FROM`) or SMTP.\n7. Set `NODE_ENV=production`.\n8. Set `BODY_SIZE_LIMIT=140M` (or rely on `npm start`, which defaults to `140M` when unset). A value pinned to the old `40M` rejects the 100 MB artifacts the Pro plan allows.\n9. Migrations run automatically on each deploy via `railway.toml` (`preDeployCommand: npm run db:migrate`).\n10. Use `npm run build` as the build command and `npm start` as the start command.\n\n**Existing production database (legacy `ensureSchema` → Drizzle):** on the first Drizzle deploy,\n`npm run db:migrate` detects an existing `users` table, records the baseline migration in\n`drizzle.__drizzle_migrations` without re-running `CREATE TABLE`, then applies any newer\nmigrations. No manual cutover is required for arelay.app-style databases that already match\nthe current schema. For a truly fresh host, run migrations on an empty database instead; if\nyou are rebuilding from scratch, copy only `users`, `webauthn_credentials`, `e2ee_config`, and\n`agent_api_tokens` from the old database.\n\nPoint agents at your deployment URL: `ARELAY_URL=https://your-domain.example`.\n\n### Backup and restore (self-hosting)\n\nAgent Relay is not a backup or archival service — keep independent copies of important\ncontent. Self-hosted operators are responsible for backups (see [SECURITY.md](SECURITY.md)).\n\nBack up **both** stores; restoring only one leaves the deployment broken:\n\n| Store                          | Contents                                                                          |\n| ------------------------------ | --------------------------------------------------------------------------------- |\n| PostgreSQL                     | Accounts, passkeys, E2EE config, API tokens, inbox session metadata, email drafts |\n| S3 (`S3_BUCKET` / `S3_PREFIX`) | Encrypted artifact blobs referenced by `inbox_artifacts.storage_key`              |\n\n**Backup**\n\n```bash\n# PostgreSQL (custom format; adjust connection string)\npg_dump \"$DATABASE_URL\" -Fc -f agent-relay-$(date +%Y%m%d).dump\n\n# S3 prefix (AWS CLI example; use your provider's equivalent)\naws s3 sync \"s3://${S3_BUCKET}/${S3_PREFIX}/\" \"./agent-relay-s3-$(date +%Y%m%d)/\"\n```\n\nUse your host's managed snapshots (Railway Postgres, S3 versioning, etc.) when available.\n\n**Restore**\n\n1. Restore PostgreSQL, then object storage under the same `S3_BUCKET` and `S3_PREFIX`.\n2. Keep the same `SESSION_SECRET` — encrypted Cloudflare credentials in the database cannot\n   be decrypted after restore if this value changes.\n3. Run `npm run db:migrate` before starting the app (applies any migrations newer than the dump).\n4. Spot-check: sign in with a passkey, open a session, download an artifact.\n\nDelivered content stays E2EE-encrypted in backups. Recovery still requires the account\npasskey and portal unlock; backups do not grant server-side plaintext access.\n\n### Plugins\n\nOptional features ship as plugins so minimal self-hosts stay lean. Plugin tables are\nincluded in the Drizzle migrations; enable each plugin with an environment variable to\nturn on its APIs and UI.\n\n#### Email Review Relay\n\nAgents submit outbound email drafts for human review before send. On [arelay.app](https://arelay.app)\nthe plugin is enabled by default; self-hosters set `EMAIL_REVIEW_RELAY_ENABLED=true`. When\ndisabled, plugin APIs return `404` and the portal UI is hidden.\n\n**Account setup (portal):** open **Account** (`/portal/account`) → **Email sending (Cloudflare API)**\nand paste your Cloudflare Account ID and API token.\nThese per-user credentials are encrypted server-side and used only when you approve a draft.\nSystem `CLOUDFLARE_*` env vars remain for signup verification only.\n\n**Agent API:** authenticated agents POST encrypted drafts to `/api/agent/email-drafts`\n(`encrypted: true` with envelope fields). Plaintext drafts are rejected.\n\n```json\n{\n\t\"encrypted\": true,\n\t\"encrypted_to\": { \"v\": 1, \"alg\": \"P-256-ECDH-A256GCM\", \"...\": \"...\" },\n\t\"encrypted_from_email\": { \"...\": \"...\" },\n\t\"encrypted_subject\": { \"...\": \"...\" },\n\t\"encrypted_html\": { \"...\": \"...\" },\n\t\"idempotency_key\": \"optional-stable-key\"\n}\n```\n\nThe response includes the inbox session and draft (`status: pending`). Poll draft status\nwith `GET /api/agent/email-drafts/{id}` or `GET /api/agent/sessions/{id}` (includes\n`email_draft` when applicable).\n\n**Human review (portal):** open the session, decrypt and preview the HTML, then **Approve**\n(sends via your Cloudflare credentials) or **Reject** (no send). Approve sends decrypted\nfields in the request body so mail can be sent without storing plaintext server-side.\nApprove requires Cloudflare Email Sending to be configured on the account.\n\nBase64 `data:image/...` sources in approved HTML are converted in the browser to CID inline\nattachments before sanitization and send. This keeps the encrypted portal preview\nself-contained while making embedded images compatible with Gmail and other email clients.\n\n### Tech stack\n\n- SvelteKit 2, Svelte 5, TypeScript, Tailwind CSS\n- PostgreSQL, S3-compatible object storage\n- WebAuthn/passkeys\n\n---\n\n## Contributing & help wanted\n\nAgent Relay is open source (MIT) and built in the open — contributions of all sizes are\nwelcome, and there's real room to have an impact while the project is young.\n\nThe fastest way in is to **build an integration**. Most integrations talk to the HTTP API\nthrough the [`@arelay/cli`](./packages/arelay) SDK and never touch the core app, so you can\nship something useful without learning the whole codebase or the encryption internals. The\n[**Building integrations guide**](./docs/building-integrations.md) walks through four levels\n— from a dozen-line delivery script to a full server-side feature plugin — with working\nexamples.\n\nA few things that would genuinely help:\n\n- Delivery bridges and notifiers (Slack, Discord, Telegram)\n- A GitHub Action for delivering CI artifacts\n- Platform plugins for more agent runners\n- An additional email backend (e.g. SMTP) for Email Review Relay\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for dev setup and conventions. Rough ideas are\nwelcome — open an issue to start a conversation.\n\n---\n\n## Security model\n\nThe hosted service publishes a plain-language [security page](https://arelay.app/security):\nwhat is encrypted, what the server can see, the one exception at approval time, the\ncredentials it holds, subprocessors, and known limits. In brief:\n\n- Human login uses passkeys and signed session cookies.\n- Agent access uses named bearer tokens; only hashes are stored server-side.\n- Agent tokens require E2EE setup; an encrypted copy of each token is stored for reveal in the browser.\n- All agent content uses P-256 ECDH and AES-256-GCM envelopes; decryption happens client-side.\n- Server preview/download/archive APIs return `e2ee_only`; the portal decrypts via ciphertext endpoints.\n- HTML and Markdown previews render in sandboxed iframes; external URLs are stripped. Users can optionally open HTML artifacts or email drafts in a new browser tab to view unsanitized content they trust.\n- Artifact uploads are capped at 25 MB per file and 500 MB per account.\n- Download and preview URLs are short-lived.\n\nReport security issues privately as described in [SECURITY.md](./SECURITY.md).\n\n## License\n\nAgent Relay is released under the [MIT License](./LICENSE).\n",
  "bytes": 24898,
  "sha": "5df13fc809b8cee845e535540c9e276f09dfe7830268986eabe771e76c0edbcd",
  "repo_slug": "mmmikael/arelay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mmmikael_arelay_0edb98f4/readme"
}