Agent Mailbox

Agent Mailbox는 자동화된 테스트와 AI 에이전트에게 가입, 인증, 매직 링크, 비밀번호 재설정 흐름에 사용할 수 있는 단기 이메일 주소를 제공합니다. 자체 Cloudflare 계정에서 실행되며 JSON API와 상태 비저장(stateless) MCP 엔드포인트를 모두 노출합니다.

각 주소에는 별도의 무작위 사서함 토큰이 있습니다. 메시지는 SQLite 기반 Durable Object에 저장되고, 첨부 파일은 R2에 저장되며, 알람이 TTL(만료 시간)이 지나면 사서함을 삭제합니다.

빠른 시작

Node.js 24 이상과 활성 도메인이 하나 이상 있는 Cloudflare 계정이 필요합니다. 새 복사본을 만들어 배포하려면:

npx create-agent-mailbox@latest

create-agent-mailbox 패키지는 첫 공개 릴리스가 게시되면 사용할 수 있습니다. 그때까지는 이 저장소를 클론하고 다음을 실행하세요:

pnpm install
pnpm run setup

TypeScript CLI는 Wrangler의 브라우저 로그인을 사용하고, 계정의 활성 영역(zone)을 로드하며, 전용 mail.<domain> 및 mailbox.<domain> 호스트 이름을 권장합니다. 변경 사항을 적용하기 전에 하나의 배포 계획을 보여줍니다. 승인되면 이메일 라우팅, 하위 주소 지정(subaddressing) 및 이메일 전송을 구성하고, 프로젝트 검사를 실행한 다음 Worker를 배포합니다. Cloudflare는 Worker 구성에서 R2 버킷, Durable Object, DNS 레코드 및 인바운드 주소 규칙을 프로비저닝합니다. 선택한 영역의 계정이 생성된 Worker 구성에 고정되므로 Wrangler가 다시 선택하도록 요청하지 않습니다.

부트스트래퍼는 Corepack을 사용하여 저장소의 정확한 pnpm 잠금 파일을 설치합니다. pnpm을 전역적으로 설치할 필요는 없습니다.

배포 후 동일한 흐름으로 Codex 또는 Claude Code를 연결하고 번들로 제공되는 Agent Mailbox 스킬을 설치할 수 있습니다. 클라이언트는 로컬 자격 증명 브리지의 경로만 받습니다. API 키는 무시되는 mode-0600 자격 증명 파일에 남아 있습니다. 연결한 후 이미 열려 있는 클라이언트를 다시 시작하세요.

선택한 각 영역에는 영역 이름을 딴 격리된 Worker(예: agent-mailbox-example-com)가 생성됩니다. 동일한 Cloudflare 계정의 여러 도메인에 Agent Mailbox를 배포할 수 있으며, 한 설정이 다른 도메인의 라우팅, 저장소, 비밀 또는 구성을 대체하지 않습니다. 각 장기 배포를 자체 프로젝트 디렉터리에 유지하여 생성된 구성과 자격 증명을 계속 사용할 수 있도록 하세요. 예를 들어 두 번째 도메인에는 npx create-agent-mailbox@latest mailbox-example-net을 사용하세요.

Wrangler에 여러 인증 프로필이 있는 경우 설정에서 영역을 로드하기 전에 사용할 프로필을 묻습니다. 단일 프로필은 자동으로 선택됩니다. 스크립트 설정의 경우 --profile <name>을 명시적으로 전달하세요.

Wrangler OAuth로 충분합니다. 별도의 Cloudflare API 토큰을 만들 필요는 없습니다. DNS 가용성 검사는 Cloudflare의 공용 DNS 리졸버를 사용하며, Wrangler는 배포 중 최종 사용자 지정 도메인 충돌 확인을 처리합니다.

CLI는 마스터 API 키를 생성하여 표준 입력을 통해 Wrangler에 전송하므로 명령줄에 절대 나타나지 않습니다. 로컬 복사본은 무시되는 .agent-mailbox.credentials.json 파일에 mode 0600으로 기록됩니다. 이것이 API 또는 MCP 클라이언트에 제공할 자격 증명입니다. 로컬 복사본을 유지하지 않으려면 비밀번호 관리자로 옮기세요.

유용한 설정 모드:

# Validate local setup code and configuration. No login or Cloudflare changes.
pnpm mailbox deploy --check

# Log in, select a zone, and inspect DNS, but make no changes.
pnpm mailbox deploy --plan

# Scripted use after Wrangler is already authenticated.
pnpm mailbox deploy --zone example.com --yes

pnpm run setup은 pnpm mailbox deploy의 호환 별칭으로 유지됩니다.

배포 관리

Agent Mailbox는 별도의 로컬 레지스트리를 유지하지 않고 Cloudflare를 진실의 원천(source of truth)으로 사용합니다:

# Find every Agent Mailbox Worker accessible to a Wrangler profile.
pnpm run list

# Check Worker bindings, custom domain, Email Routing, MX records, health,
# local credentials, and authenticated MCP connectivity.
pnpm run doctor

# Configure an installed MCP client and copy the portable Agent Skill.
pnpm run connect

# Safely remove one deployment after showing its exact Cloudflare resources.
pnpm run teardown

# Remove this checkout's MCP client connections and optionally its credentials.
pnpm run disconnect

# Empty and delete an R2 bucket retained by an earlier teardown.
pnpm run purge-data

list는 현재 체크아웃의 자격 증명과 일치하는 배포를 보여줍니다. doctor는 기본적으로 wrangler.jsonc의 Worker를 검사합니다. 다른 검색된 인스턴스를 검사하려면 Worker 이름, 이메일 도메인 또는 MCP 호스트 이름을 전달하세요. API 키를 로컬에서 사용할 수 없는 인스턴스의 인증된 MCP 검사는 건너뜁니다.

비대화형 클라이언트 설정의 경우 하나 이상의 클라이언트를 명시적으로 선택하세요:

pnpm run connect --client codex --yes
pnpm run connect --client codex --client claude --yes

번들 스킬은 선택한 클라이언트의 사용자 스킬 디렉터리에 설치됩니다. MCP 연결만 원하는 경우 --no-skill을 사용하세요. 내용이 다른 기존 클라이언트 연결 또는 스킬 디렉터리는 변경되지 않습니다.

배포 제거

teardown은 검색된 인스턴스 하나를 선택하고 전체 Worker 이름을 확인으로 요구합니다. 해당 Worker의 정확한 인바운드 이메일 라우팅 규칙, 사용자 지정 도메인, Worker 및 Durable Object 네임스페이스만 제거합니다. 공유 영역 수준의 이메일 라우팅 DNS, 하위 주소 처리, 이메일 전송 및 기타 Agent Mailbox 배포는 변경되지 않습니다.

# Inspect the exact removal plan without changing Cloudflare.
pnpm run teardown -- agent-mailbox-example-com --dry-run

# Remove the Worker while retaining its R2 attachment bucket.
pnpm run teardown -- agent-mailbox-example-com

# Irreversibly empty and delete the attachment bucket as well.
pnpm run teardown -- agent-mailbox-example-com --purge-data

작업은 Worker가 마지막에 삭제되도록 순서가 지정됩니다. 이전 단계가 실패하면 동일한 명령을 다시 실행하여 안전하게 계속하세요. 무인 사용의 경우 인스턴스, Wrangler 프로필 및 --yes를 명시적으로 제공하세요.

teardown이 첨부 파일을 보관할 때 프로젝트 디렉터리에 무시되는 mode-0600 정리 영수증을 기록합니다. 이렇게 하면 Worker가 사라진 후에도 정확한 계정과 버킷을 계속 찾을 수 있습니다. 나중에 다음으로 삭제하세요:

pnpm run purge-data

로컬 정리를 위해 disconnect를 별도로 사용하세요. 기본적으로 선택한 MCP 연결을 제거하고 자격 증명과 공유 스킬은 유지합니다. 대화형 모드에서는 일치하는 자격 증명 삭제를 제안하며, 스크립트 사용에는 --remove-credentials가 필요합니다. 스킬은 여러 배포에 사용할 수 있으므로 명시적인 --remove-skill 옵션으로만 삭제됩니다.

재배포, 업데이트 및 자격 증명 교체

동일한 도메인에 대해 설정을 다시 실행하는 것은 안전한 재배포입니다. 이 프로젝트에 일치하는 로컬 자격 증명이 있으면 설정은 연결된 클라이언트를 무효화하지 않고 동일한 마스터 API 키를 다시 설치합니다. 키를 교체하려면 항상 명시적인 선택 또는 --rotate-credentials가 필요합니다.

향후 태그된 릴리스에서 배포를 업데이트하려면 배포하지 않고 새 소스를 만들고, 이전 프로젝트에서 생성된 구성과 무시된 자격 증명을 복사하고, 변경 사항을 검토한 다음 설정을 실행하세요:

npx create-agent-mailbox@X.Y.Z agent-mailbox-next --no-deploy
cp agent-mailbox/wrangler.jsonc agent-mailbox/.agent-mailbox.credentials.json agent-mailbox-next/
cd agent-mailbox-next
corepack pnpm run setup
corepack pnpm run doctor

doctor가 성공할 때까지 이전 디렉터리를 유지하세요. Wrangler는 롤백을 위해 이전 Worker 버전을 유지합니다. 로컬 자격 증명을 사용할 수 없는 경우 --rotate-credentials가 제공되지 않으면 설정은 비대화형 교체를 거부합니다.

안전 모델

• 마스터 API 키가 모든 API 및 MCP 요청을 보호합니다.

• 별도의 사서함 토큰이 각 생성된 사서함을 보호합니다.

• 사서함은 구성된 최대 TTL 이후 자동으로 만료됩니다.

• 알 수 없거나 만료된 주소로 들어오는 메일은 거부됩니다.

• 이메일 내용은 신뢰할 수 없는 데이터입니다. 링크 및 코드 추출은 결정적입니다.

• 발신 전송은 사서함별로 속도가 제한되며 테스트 메일 전용입니다.

• 사서함 데이터가 포함된 API 응답은 Cache-Control: no-store를 사용합니다.

강력한 마스터 API 키 없이 배포를 노출하지 마세요. 이 프로젝트는 자체 호스팅 테스트 도구이며 공개 임시 이메일 서비스가 아닙니다.

요구 사항

• Node.js 24 이상. 클론에서 개발할 때만 pnpm 10이 필요합니다.

• Cloudflare에 도메인이 있는 Cloudflare 계정.

• 해당 도메인에 대한 Cloudflare 이메일 라우팅 및 이메일 전송 액세스.

CLI는 루트 도메인을 대신하지 않고 전용 하위 도메인을 요구합니다. Agent Mailbox는 inbox+purpose-random@mail.example.com과 같은 주소를 만듭니다. 일부 서비스는 + 별칭을 거부하거나 정규화합니다. 이러한 서비스는 향후 릴리스에서 전용 catch-all 구현이 필요할 수 있습니다.

수동 배포

설정 CLI가 권장 경로입니다. 다음은 동등한 수동 단계입니다.

1. Worker 구성

wrangler.jsonc를 편집하고 모든 example.com 값을 교체하세요:

• name은 Cloudflare 계정의 각 Agent Mailbox 배포에 대해 고유해야 합니다.

• addresses[0]는 인바운드 기본 주소이며, 일반적으로 inbox@<EMAIL_DOMAIN>입니다.

• routes[0].pattern은 공개 API 및 MCP 호스트 이름입니다.

• vars.EMAIL_DOMAIN은 생성된 주소에 사용되는 도메인입니다.

• vars.MCP_HOSTNAME은 MCP 전송이 허용하는 호스트 이름입니다.

바인딩 이름을 변경하면 pnpm exec wrangler types를 실행하고 업데이트된 worker-configuration.d.ts를 커밋하세요.

2. 도메인 수준 이메일 기능 프로비저닝

Cloudflare 대시보드에서 Compute → Email Service를 엽니다:

1. 수신 도메인 온보딩.

2. 이메일 라우팅 설정에서 하위 주소 처리를 활성화합니다.

3. 이메일 전송에서 동일한 도메인을 온보딩합니다.

Wrangler addresses 항목은 Worker가 배포될 때 인바운드 주소 규칙을 생성하지만, DNS, 영역 수준 라우팅, 하위 주소 처리 및 전송 자격은 이미 구성되어 있어야 합니다.

3. 검증 및 배포

pnpm check
pnpm deploy

Wrangler는 wrangler.jsonc에서 R2 버킷, Durable Object, 사용자 지정 호스트 이름 및 인바운드 주소 규칙을 프로비저닝합니다. 이는 애플리케이션을 Cloudflare 계정에 배포합니다. 이 Git 저장소를 게시하지 않습니다.

4. 배포 보호

비밀번호 관리자에서 길고 무작위한 값을 만든 다음 Wrangler의 대화형 프롬프트에 입력하세요:

pnpm exec wrangler secret put AGENT_API_KEY

이 값을 wrangler.jsonc, 셸 명령 또는 소스 제어에 절대 넣지 마세요.

5. 배포 검증

공개 상태 엔드포인트를 검증하세요:

curl https://mailbox.example.com/health

호스트 이름을 구성된 경로로 교체하세요. 성공적인 응답은 {"ok":true}입니다.

로컬 개발

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

Worker를 시작하기 전에 .dev.vars의 예제 비밀을 교체하세요. 로컬 Durable Object 및 R2 상태는 무시되는 .wrangler 디렉터리에 저장됩니다.

다음으로 전체 검증 스위트를 실행하세요:

pnpm check

JSON API

모든 사서함 경로에는 마스터 키가 필요합니다:

Authorization: Bearer <AGENT_API_KEY>

사서함별 작업에는 생성 시 반환된 토큰도 필요합니다:

X-Mailbox-Token: <MAILBOX_TOKEN>

사서함 생성

curl -X POST https://mailbox.example.com/api/mailboxes \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"signup","ttlSeconds":3600}'

응답에는 address, mailboxToken 및 expiresAt가 포함됩니다. 사서함 토큰을 저장하세요. 복구할 수 없습니다.

인증 이메일 대기

curl "https://mailbox.example.com/api/mailboxes/$ADDRESS/wait?subject=verify&timeoutSeconds=20" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "X-Mailbox-Token: $MAILBOX_TOKEN"

경로:

• POST /api/mailboxes

• GET /api/mailboxes/:address/messages

• GET /api/mailboxes/:address/messages/:id

• GET /api/mailboxes/:address/messages/:id/links

• GET /api/mailboxes/:address/messages/:id/codes

• GET /api/mailboxes/:address/messages/:id/attachments/:index

• GET /api/mailboxes/:address/wait

• POST /api/mailboxes/:address/send

• DELETE /api/mailboxes/:address

• GET /health

첨부 파일 인덱스는 완전한 메시지와 함께 반환되는 attachments 배열에서 가져오며 0부터 시작합니다.

MCP

Streamable HTTP 엔드포인트는 https://<your-hostname>/mcp입니다. MCP 클라이언트를 해당 URL과 다음 헤더로 구성하세요:

Authorization: Bearer <AGENT_API_KEY>

사용 가능한 도구:

• create_mailbox

• wait_for_email

• list_emails

• get_email

• get_links

• get_codes

• send_email

• delete_mailbox

가장 쉬운 클라이언트 설정은:

pnpm run connect

이것은 Codex 및 Claude Code를 지원합니다. 각 배포에 고유한 MCP 연결 이름을 제공하여 클라이언트가 여러 Agent Mailbox 도메인을 구분할 수 있습니다.

선택적 stdio 브리지

이전 MCP 클라이언트는 이 프로젝트의 종속성에서 mcp-remote를 실행하는 bin/agent-mailbox-mcp를 사용할 수 있습니다. 자동 설정 후 .agent-mailbox.credentials.json에서 엔드포인트와 키를 읽습니다:

bin/agent-mailbox-mcp

환경 변수로 생성된 값을 재정의할 수 있습니다:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_API_KEY='<master-api-key>'
bin/agent-mailbox-mcp

그래픽 Linux 클라이언트의 경우 환경 변수 대신 Secret Service에 키를 저장하고 다음 비밀 아님 조회 속성을 구성하세요:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_KEYRING_SERVICE=agent-mailbox
export AGENT_MAILBOX_KEYRING_ACCOUNT=agent-mailbox
bin/agent-mailbox-mcp

운영

• 기본 사서함 TTL: 하루.

• 최대 사서함 TTL: 7일.

• 기본 발신 한도: 사서함당 UTC 하루 20개 메시지.

• Workers 로그 및 추적은 wrangler.jsonc에서 활성화됩니다. 예상 트래픽과 예산에 맞게 샘플링을 조정하세요.

• 사서함을 삭제하거나 만료하면 R2 첨부 파일도 삭제됩니다.

마스터 API 키와 모든 사서함 토큰을 자격 증명으로 취급하세요. 이메일 본문, 헤더, 링크, 코드 및 첨부 파일에는 개인 또는 민감한 데이터가 포함될 수 있습니다.

지원, 기여 및 보안

재현 가능한 버그, 기능 요청 및 일반적인 사용 질문은 GitHub 이슈를 열어주세요. 개발 지침은 CONTRIBUTING.md를, 비공개 취약점 보고는 SECURITY.md를 참조하세요. 이슈에 자격 증명, 사서함 내용 또는 개인 배포 식별자를 포함하지 마세요.

라이선스

Agent Mailbox는 MIT License로 제공됩니다.