Agent Relay

Agent Relay

Agent Relay 是 AI Agent 请求授权的地方。Agent 可以起草邮件、申请支出，并将完成的工作发送到端到端加密的私人收件箱；在你批准之前，任何内容都不会离开、发送或产生费用。任何能够发出 HTTP 请求的工具都可以使用它——Cursor、Codex、Claude Code、cron 作业、webhook 或你自己的后端均可。它基于 MIT 许可证开源，因此你可以自行运行。

可选的 Email Review Relay 插件提供一条有人参与的外发邮件流程：Agent 提交加密草稿，你在同一个收件箱中预览，然后选择批准或拒绝，之后才会发送邮件。该功能已在 arelay.app 启用；自托管用户可以通过 EMAIL_REVIEW_RELAY_ENABLED=true 开启（设置）。

两种使用方式：

• arelay.app — 托管服务；注册并连接你的 Agent （无需部署）。
• 自托管 — 在你自己的基础设施上运行此仓库，遵循 MIT 许可证。

目录

使用 arelay.app

• 开始使用
• 连接你的 AI Agent
• 加密（必需）
• Email Review Relay
• 功能

自托管

• 开发环境设置
• 环境变量
• 部署到生产环境
• 插件
• 技术栈

参考

• 贡献与帮助需求
• 安全模型
• 服务条款 · 隐私政策
• 贡献
• 许可证

---

使用 arelay.app

arelay.app 上的托管服务负责部署、数据库、存储、备份、TLS 和更新。其安全模型与自托管相同：加密的投递内容会在你的浏览器中解密，而不是在服务器上解密。唯一的例外是批准邮件草稿：解密后的邮件会在该请求中发送到服务器，以便服务器进行投递，但绝不会以明文形式存储。邮件本身并非端到端加密，因此收件人的邮件服务提供商会永久看到相同的内容。

快速开始

1. 打开 arelay.app 并使用通行密钥创建账户。
2. 注册时接受服务条款和 隐私政策（托管服务要求）。
3. 首次访问门户时完成设置加密（通行密钥 + 恢复密钥）。
4. 在门户中打开账户 → Agent 令牌，为每个 Agent 或集成创建一个命名令牌。
5. 只复制一次令牌——它仅在创建时显示。
6. Agent 发送投递内容后，收件箱会自动更新（每隔几秒刷新一次）。

登录使用通行密钥（WebAuthn），而非密码或社交账号登录。无需 Google、Apple 或 Microsoft 账户。如果条款或隐私政策之后更新，现有账户在继续使用前会收到接受新版本的提示。

连接 AI Agent

Agent Relay 不限于特定 Agent：任何支持 HTTP 并遵循 E2EE 信封格式的客户端都可以投递内容。选择适合你设置的方式：

集成方式	适用场景
CLI 和 MCP 服务	最快上手：在任意 shell 中运行一条命令，或在 Claude Code、Cursor 和 Claude Desktop 中使用原生 MCP 工具
Agent 技能	Cursor、Codex、Claude Code、Hermes Agent，以及其他支持 Agent Skills 的宿主
直接 HTTP API	自定义脚本、后端、webhook、定时任务
平台插件	特定平台的钩子，例如 Hermes cron 投递

无论选择哪种方式，都要在 Agent 运行的环境中设置以下变量——切勿提交令牌：

变量	arelay.app 对应的值
ARELAY_URL	https://arelay.app
ARELAY_TOKEN	来自账户 → Agent 令牌的令牌

每个请求都使用 Authorization: Bearer <ARELAY_TOKEN>。

CLI 和 MCP 服务

@arelay/cli npm 包封装了 API 和所有信封加密功能。 可从任意 shell 投递内容：

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

也可以将其注册为 MCP 服务，让 Agent 原生投递工作 （deliver_to_inbox、list_inbox_sessions、submit_email_draft 工具）：

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

npx -y @arelay/cli check 可验证令牌和加密设置。该包还导出了一个类型化 SDK（import { ArelayClient } from '@arelay/cli'）——请参阅其 README。可自托管用户可通过 ARELAY_URL 将其指向自己的部署。

Agent 技能

安装 agent-relay 技能（需要 门户 E2EE 设置）：

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

Hermes Agent：

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

直接 HTTP API

任何能够 POST JSON 的程序都可以投递内容：从 GET /api/agent/e2ee/config 获取公钥，在本地加密，创建会话并上传制品。请参阅 API 参考 以及技能包中提供的 Node 参考脚本，了解可用的加密代码。

平台插件

Hermes cron（--deliver arelay）需要 arelay-hermes-plugin。 cron 在网关中运行，而非交互式 CLI 中——将凭据放入 ~/.hermes/.env（包括 AGENT_RELAY_HOME_CHANNEL=https://arelay.app），安装插件，然后重启网关：

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

加密（必需）

所有 Agent 交付内容都必须进行端到端加密。在开始使用期间完成设置加密；查看收件箱时，在浏览器中解锁。Agent 从 GET /api/agent/e2ee/config 获取你的公钥，并上传加密后的会话和制品。明文 Agent 负载会返回 400（plaintext_not_allowed）；未配置的账户会返回 428（e2ee_required）。

电子邮件审核中继

在 arelay.app 上，Agent 以 POST 方式提交加密的电子邮件草稿；每封草稿都会显示为一个收件箱会话，你可以批准（使用你的 Cloudflare 凭据发送）或拒绝。

1. 账户 → 电子邮件发送（Cloudflare API） — 保存你的 Cloudflare 账户 ID 和 API 令牌（在服务器端加密；仅在你批准时使用）。
2. 使用 agent-relay 技能 — 草稿使用与文件交付相同的 E2EE 信封。

API 详情和自托管设置：插件。

功能

• 适合移动设备的电子邮件风格收件箱
• 电子邮件审核中继：Agent 起草外发邮件；你批准后才会发送
• 制品预览和下载（文本、Markdown、HTML、PDF、图像）
• 沙盒 HTML/Markdown 预览（移除外部链接和媒体）
• 仅支持端到端加密交付
• 通行密钥登录（每个账户一个通行密钥）
• 可命名的 Agent API 令牌，支持单独撤销
• 存储限制：每个制品 25 MB，每个账户 500 MB

---

自托管

在你自己的 PostgreSQL 和 S3 兼容存储上运行 Agent Relay。适用于需要完全控制数据驻留或进行私有部署的场景。

开发环境设置

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

打开 http://127.0.0.1:5173，并使用通行密钥创建账户。 如果未配置 Cloudflare 或 SMTP，验证码会打印到服务器控制台。

数据库架构变更由 Drizzle 迁移管理。编辑 Drizzle 架构，使用 npm run db:generate 生成迁移，检查生成的 SQL，然后使用 npm run db:migrate:local 应用迁移。

运行单元测试：

npm test

要针对一次性空数据库测试迁移，请设置 TEST_DATABASE_URL 并运行：

npm run db:smoke

环境变量

变量	描述
SESSION_SECRET	用于签名人工会话 Cookie 的密钥。使用 openssl rand -hex 32 生成。
SESSION_VERSION	增大此值以使现有人工会话失效。
ORIGIN	用于 CSRF 检查和绝对链接的公开站点 URL。在生产环境中，将其设置为规范 URL，例如 https://arelay.app。
WEBAUTHN_RP_NAME	通行密钥依赖方的显示名称。默认为 Agent Relay。
WEBAUTHN_RP_ID	通行密钥依赖方 ID。在 arelay.app 上的生产环境中，使用 arelay.app。
WEBAUTHN_ORIGIN	预期的通行密钥来源，例如 https://arelay.app。
DATABASE_URL	PostgreSQL 连接字符串。
CLOUDFLARE_ACCOUNT_ID	用于邮件发送的 Cloudflare 账户 ID。发送域名使用 Cloudflare DNS 时使用。
CLOUDFLARE_API_TOKEN	具有邮件发送权限的 Cloudflare API 令牌。
EMAIL_FROM	配置 Cloudflare 或 SMTP 时为必填项。验证邮件的发件人地址，例如 Agent Relay <[email protected]>。
SMTP_HOST	用于账户邮件验证的 SMTP 主机。未配置 Cloudflare 邮件发送时使用。
SMTP_PORT	SMTP 端口。默认为 587；当 SMTP_SECURE=true 时默认为 465。
SMTP_SECURE	对隐式 TLS SMTP 设置为 true。
SMTP_USER	SMTP 用户名（如果你的服务提供商要求身份验证）。
SMTP_PASSWORD	SMTP 密码（如果你的服务提供商要求身份验证）。
S3_ENDPOINT	兼容 S3 的端点 URL。
S3_BUCKET	S3 存储桶名称。
S3_PREFIX	对象键前缀。默认为 agent-relay。
S3_ACCESS_KEY	S3 访问密钥。
S3_SECRET_KEY	S3 密钥。
S3_REGION	S3 区域。默认为 us-east-1。
PORT	npm start 使用的 HTTP 端口。默认为 3000。Railway 会自动设置此值。
BODY_SIZE_LIMIT	adapter-node 的最大 HTTP 请求正文大小。加密文件上传需要此设置（一个 25 MB 的文件需要约 37 MB 的 JSON；Pro 套餐的 100 MB 需要约 140 MB）。使用 npm start 时默认为 140M。
NODE_ENV	在生产环境中设置为 production，使会话和 WebAuthn Cookie 使用 Secure。
EMAIL_REVIEW_RELAY_ENABLED	可选插件。设置为 true 以启用邮件审阅中继（默认关闭）。
同时配置 Cloudflare Email Sending 和 SMTP 时，将使用 Cloudflare。

部署到生产环境

要求：

• PostgreSQL
• 兼容 S3 的对象存储（参见 scripts/iam-agent-relay-s3-policy.json，其中包含一份作用域限定为 agent-relay/ 前缀的最简 AWS IAM 策略）
• 用于账号验证的邮件投递服务（Cloudflare Email Sending 或 SMTP）
• 稳定的 HTTPS 源站，并正确配置 WebAuthn RP 设置

构建并运行：

npm run db:migrate:local
npm run build
npm start

对于全新的生产数据库，请在启动应用前运行迁移。如果要从旧数据库迁移早期的账号／身份验证记录，只复制 users、webauthn_credentials、e2ee_config 和 agent_api_tokens；收件箱／内容／插件表保持为空。

Railway：

1. 从 github.com/mmmikael/arelay 创建新服务。
2. 添加 PostgreSQL 并关联 DATABASE_URL。
3. 添加兼容 S3 的存储凭据。
4. 设置 SESSION_SECRET。
5. 为你的域名设置 WEBAUTHN_RP_ID 和 WEBAUTHN_ORIGIN。
6. 配置邮件投递：Cloudflare Email Sending（CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN、EMAIL_FROM）或 SMTP。
7. 设置 NODE_ENV=production。
8. 设置 BODY_SIZE_LIMIT=140M（或使用 npm start，未设置时默认值为 140M）。若固定为旧值 40M，Pro 套餐允许的 100 MB 文件将无法通过。
9. 每次部署时，迁移都会通过 railway.toml 自动运行（preDeployCommand: npm run db:migrate）。
10. 将 npm run build 设为构建命令，并将 npm start 设为启动命令。

**现有生产数据库（从旧版 ensureSchema 迁移到 Drizzle）：**首次部署 Drizzle 时，npm run db:migrate 会检测到现有的 users 表，在 drizzle.__drizzle_migrations 中记录基线迁移，而不会重新运行 CREATE TABLE，随后应用所有较新的迁移。对于架构已与当前版本匹配的 arelay.app 风格数据库，无需手动切换。对于真正的全新主机，请改为在空数据库上运行迁移；如果要从头重建，只从旧数据库复制 users、webauthn_credentials、e2ee_config 和 agent_api_tokens。

将 Agent 指向你的部署 URL：ARELAY_URL=https://your-domain.example。

备份与恢复（自托管）

Agent Relay 不是备份或归档服务——请为重要内容保留独立副本。自托管运营方需自行负责备份（参见 SECURITY.md）。

两个存储都必须备份；只恢复其中一个会导致部署无法正常运行：

存储	内容
PostgreSQL	账号、通行密钥、E2EE 配置、API 令牌、收件箱会话元数据、邮件草稿
S3（S3_BUCKET / S3_PREFIX）	inbox_artifacts.storage_key 引用的加密文件内容

备份

# PostgreSQL (custom format; adjust connection string)
pg_dump "$DATABASE_URL" -Fc -f agent-relay-$(date +%Y%m%d).dump

# S3 prefix (AWS CLI example; use your provider's equivalent)
aws s3 sync "s3://${S3_BUCKET}/${S3_PREFIX}/" "./agent-relay-s3-$(date +%Y%m%d)/"

条件允许时，请使用托管服务提供的快照（Railway Postgres、S3 版本控制等）。

恢复

1. 先恢复 PostgreSQL，再将对象存储恢复到相同的 S3_BUCKET 和 S3_PREFIX 下。
2. 保持 SESSION_SECRET 不变——如果该值发生变化，恢复后数据库中加密的 Cloudflare 凭据将无法解密。
3. 启动应用前运行 npm run db:migrate（应用转储文件之后新增的所有迁移）。
4. 抽查：使用通行密钥登录、打开会话、下载文件。

已投递的内容在备份中仍保持 E2EE 加密。恢复仍需要账号通行密钥和门户解锁；备份不会授予服务端访问明文的权限。

插件

可选功能以插件形式提供，让精简的自托管部署保持轻量。插件表包含在 Drizzle 迁移中；通过环境变量启用各插件，即可开启其 API 和 UI。

Email Review Relay

Agent 在发送邮件前，会提交外发邮件草稿供人工审核。在 arelay.app 上，该插件默认启用；自托管用户需设置 EMAIL_REVIEW_RELAY_ENABLED=true。禁用后，插件 API 会返回 404，门户 UI 也会隐藏。

**账户设置（门户）：**打开 账户（/portal/account）→ 邮件发送（Cloudflare API） 并粘贴你的 Cloudflare 账户 ID 和 API 令牌。 这些按用户配置的凭据会在服务端加密，仅在你批准草稿时使用。 系统 CLOUDFLARE_* 环境变量仍仅用于注册验证。

**Agent API：**经过身份验证的 Agent 会将加密草稿 POST 到 /api/agent/email-drafts （包含 encrypted: true 和信封字段）。明文草稿会被拒绝。

{
	"encrypted": true,
	"encrypted_to": { "v": 1, "alg": "P-256-ECDH-A256GCM", "...": "..." },
	"encrypted_from_email": { "...": "..." },
	"encrypted_subject": { "...": "..." },
	"encrypted_html": { "...": "..." },
	"idempotency_key": "optional-stable-key"
}

响应包含收件箱会话和草稿（status: pending）。使用 GET /api/agent/email-drafts/{id} 或 GET /api/agent/sessions/{id} 轮询草稿状态（适用时会包含 email_draft）。

**人工审核（门户）：**打开会话，解密并预览 HTML，然后选择 批准 （使用你的 Cloudflare 凭据发送）或 拒绝（不发送）。批准时会在请求正文中发送解密后的 字段，因此可以在不将明文存储在服务端的情况下发送邮件。 要批准草稿，账户必须已配置 Cloudflare Email Sending。

已批准的 HTML 中以 Base64 编码的 data:image/... 来源，会在清理和发送前由浏览器转换为 CID 内嵌 附件。这样既能让加密的门户预览保持自包含，也能让嵌入的图片兼容 Gmail 和其他邮件客户端。

技术栈

• SvelteKit 2、Svelte 5、TypeScript、Tailwind CSS
• PostgreSQL、兼容 S3 的对象存储
• WebAuthn/通行密钥

---

贡献与协助

Agent Relay 是开源项目（MIT），并以开放方式开发——欢迎各种规模的贡献；项目还处于早期阶段，有很多机会可以带来切实影响。

最快的入门方式是构建集成。大多数集成通过 @arelay/cli SDK 与 HTTP API 通信， 无需接触核心应用，因此无需了解整个代码库或加密实现，就能交付实用功能。构建集成指南介绍了四个层级， 从十几行的投递脚本到完整的服务端功能插件，并提供了可运行的示例。

以下是一些确实能带来帮助的事项：

• 投递桥接和通知工具（Slack、Discord、Telegram）
• 用于投递 CI 构建产物的 GitHub Action
• 为更多 Agent 运行器开发平台插件
• 为 Email Review Relay 增加另一个邮件后端（例如 SMTP）

有关开发环境设置和约定，请参阅 CONTRIBUTING.md。欢迎提出初步想法——打开 issue 即可开始讨论。

---

安全模型

托管服务发布了通俗易懂的安全页面，说明加密内容、服务器可见内容、批准时的唯一例外、服务器持有的凭据、子处理方和已知限制。简而言之：

• 人工登录使用通行密钥和签名会话 Cookie。
• Agent 访问使用命名的 bearer 令牌；服务端仅存储其哈希值。
• Agent 令牌需要先设置 E2EE；每个令牌的加密副本都会被存储，以便在浏览器中查看。
• 所有 Agent 内容都使用 P-256 ECDH 和 AES-256-GCM 信封；解密在客户端进行。
• 服务端预览/下载/归档 API 会返回 e2ee_only；门户通过密文端点解密。
• HTML 和 Markdown 预览会在沙盒 iframe 中渲染；外部 URL 会被移除。用户可以选择在新的浏览器标签页中打开 HTML 构建产物或邮件草稿，以查看他们信任的、未经清理的内容。
• 构建产物上传限制为每个文件 25 MB、每个账户 500 MB。
• 下载和预览 URL 均为短时有效。

请按照 SECURITY.md 中的说明私下报告安全问题。

许可证

Agent Relay 基于 MIT License 发布。