cloudflare/agentic-inbox

<div align="center"> <h1>Agentic Inbox</h1> <p><em>Cloudflare Workers에서 완전히 실행되는, AI 에이전트가 내장된 자체 호스팅 이메일 클라이언트</em></p> </div>

Agentic Inbox를 사용하면 현대적인 웹 인터페이스를 통해 이메일을 보내고, 받고, 관리할 수 있습니다. 모든 기능은 사용자 자신의 Cloudflare 계정으로 구동됩니다. 수신 이메일은 Cloudflare Email Routing을 통해 도착하며, 각 사서함은 SQLite 데이터베이스와 함께 자체 Durable Object에 격리되어 있고, 첨부 파일은 R2에 저장됩니다.

AI 기반 이메일 에이전트는 받은 편지함을 읽고, 대화를 검색하며, 답장을 작성할 수 있습니다. Cloudflare Agents SDK와 Workers AI로 구축되었습니다.

!Agentic Inbox 스크린샷

Cloudflare Email Service와 이를 Agents SDK, MCP, Wrangler CLI와 함께 사용하는 방법에 대한 자세한 내용은 블로그 게시물을 참조하세요: Email for Agents.

설정 방법

중요: 'Deploy to Cloudflare' 버튼을 클릭하는 것은 설정의 일부일 뿐입니다. 배포 후 단계도 반드시 따라야 합니다. 스크린샷이 포함된 전체 단계별 가이드는 다음 댓글을 참조하세요: https://github.com/cloudflare/agentic-inbox/issues/4#issuecomment-4269118513

설정하기

1. Cloudflare에 배포합니다. 배포 플로우는 자동으로 R2, Durable Objects, Workers AI를 프로비저닝합니다. 이메일을 수신할 도메인(yourdomain.com)을 묻는 DOMAINS 프롬프트가 표시됩니다([email protected]).

!Deploy to Cloudflare

1. Cloudflare Access 구성 -- Worker의 Settings > Domains & Routes에서 원클릭 Cloudflare Access를 활성화합니다. 모달에 POLICYAUD 및 TEAMDOMAIN 값이 표시됩니다. TEAM_DOMAIN은 Access 팀 URL 또는 전체 .../cdn-cgi/access/certs URL일 수 있습니다. 이 값을 Worker의 비밀로 설정해야 합니다.
2. Email Routing 설정 -- Cloudflare 대시보드에서 도메인 > Email Routing으로 이동하여 이 Worker로 전달되는 catch-all 규칙을 생성합니다.
3. Email Service 활성화 -- Worker가 아웃바운드 이메일을 보내려면 send_email 바인딩이 필요합니다. Email Service 문서를 참조하세요.
4. 사서함 생성 -- 배포된 앱에 방문하여 도메인의 모든 주소(예: [email protected])에 대한 사서함을 생성합니다.

Access 문제 해결

1. Invalid or expired Access token이 표시되면 일반적으로 POLICYAUD 또는 TEAMDOMAIN 비밀이 잘못된 것입니다.

• 해결 방법: Worker에 대해 Access를 껐다가 다시 켜서 Access 모달을 다시 표시한 다음, Worker 비밀을 거기에 표시된 최신 POLICYAUD 및 TEAMDOMAIN 값으로 재설정합니다.

1. Cloudflare Access must be configured in production이 표시되면, 이 애플리케이션은 의도적으로 Cloudflare Access를 적용하여 받은 편지함이 인터넷상의 누구에게도 노출되지 않도록 합니다.

• 해결 방법: Workers용 원클릭 Cloudflare Access를 사용하여 Access를 활성화한 다음, 모달 값에서 POLICYAUD 및 TEAMDOMAIN Worker 비밀을 설정합니다.

기능

• 완전한 이메일 클라이언트 — Cloudflare Email Routing을 통해 이메일을 보내고 받을 수 있으며, 리치 텍스트 작성기, 답장/전달 스레딩, 폴더 구성, 검색 및 첨부 파일을 지원합니다.
• 사서함별 격리 — 각 사서함은 SQLite 스토리지가 있는 자체 Durable Object와 첨부 파일용 R2에서 실행됩니다.
• 내장 AI 에이전트 — 읽기, 검색, 작성, 보내기를 위한 9개의 이메일 도구가 있는 사이드 패널.
• 새 이메일 자동 초안 — 에이전트가 자동으로 수신 이메일을 읽고 답장 초안을 생성하며, 보내기 전에 항상 명시적 확인을 요구합니다.
• 구성 가능하고 지속적 — 사서함별 사용자 정의 시스템 프롬프트, 지속적인 채팅 기록, 스트리밍 마크다운 응답, 도구 호출 가시성.

기술 스택

• 프론트엔드: React 19, React Router v7, Tailwind CSS, Zustand, TipTap, @cloudflare/kumo
• 백엔드: Hono, Cloudflare Workers, Durable Objects (SQLite), R2, Email Routing
• AI 에이전트: Cloudflare Agents SDK (AIChatAgent), AI SDK v6, Workers AI (@cf/moonshotai/kimi-k2.5), react-markdown + remark-gfm
• 인증: Cloudflare Access JWT 검증 (로컬 개발 외에는 필수)

시작하기

npm install
npm run dev

구성

1. wrangler.jsonc에서 도메인을 설정합니다.
2. agentic-inbox라는 R2 버킷을 생성합니다: wrangler r2 bucket create agentic-inbox

배포

npm run deploy

전제 조건

• 도메인이 있는 Cloudflare 계정
• 수신을 위해 Email Routing 활성화
• 발신을 위해 Email Service 활성화
• (에이전트용) Workers AI 활성화
• 배포/공유 환경의 경우 Cloudflare Access 구성 (프로덕션에서 필수)

공유 Cloudflare Access 정책을 통과한 모든 사용자는 설계상 이 앱의 모든 사서함에 액세스할 수 있습니다. 여기에는 /mcp의 MCP 서버도 포함됩니다. MCP를 통해 연결된 외부 AI 도구(Claude Code, Cursor 등)는 mailboxId 매개변수를 전달하여 모든 사서함에서 작동할 수 있습니다. 사서함별 권한 부여는 없습니다. Cloudflare Access 정책이 유일한 신뢰 경계입니다.

아키텍처

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Browser    │────>│  Hono Worker     │────>│  MailboxDO      │
│  React SPA   │     │  (API + SSR)     │     │  (SQLite + R2)  │
│  Agent Panel │     │                  │     └─────────────────┘
└──────┬───────┘     │  /agents/* ──────┼────>┌─────────────────┐
       │             │                  │     │  EmailAgent DO  │
       │ WebSocket   │                  │     │  (AIChatAgent)  │
       └─────────────┤                  │     │  9 email tools  │
                     │                  │────>│  Workers AI     │
                     └──────────────────┘     └─────────────────┘

라이선스

Apache 2.0 -- LICENSE 참조.