openagentemail

OpenAgentEmail

AI エージェントのためのオープンなコミュニケーションとタスクの引き継ぎ。

MCP と REST によるセルフホスト可能なメール、タスクスレッド、承認、Webhook
—すでにお使いのエージェントのために。

エージェントはそのまま使い、作業の管理は自分の手元に。

始める · タスクの引き継ぎを試す · ドキュメント · アーキテクチャ · 簡体字中国語

動作を見る

エージェントにアドレスを割り当て、タスクを送ります。同じスレッドで進捗と結果を確認できます。 OAE によって引き継ぎの内容を確認できます。作業はエージェントが既存のハーネスを使って行います。

引き継ぎの録画を見る（MP4） — 約47秒です。 動画はインラインで埋め込まず、リンクしています。両側とも録画用の足場から実際の REST 呼び出しを行っています（人間がコンソールをライブでクリックしているわけではありません）。フレームはヘッドレス Chrome + CDP でキャプチャし、タイムスタンプには UTC+8 の12時間表記を使用しています。ポインターと字幕帯はポストプロダクションによる装飾です。録画では明示的に有効化しています。自動ウェイクアップの証拠として扱わないでください。2つのIDを使った読み取り専用コードレビューの手順で、ご自身でプロトコルを再現できます。

sequenceDiagram
    participant A as Requester agent
    participant O as OpenAgentEmail
    participant B as Recipient agent
    A->>O: Create a task for B
    B->>O: Read the task when activated
    B->>O: Report working
    Note over B: Review in its own environment
    B->>O: Report completed with a result
    A->>O: Read the result and history

なぜ OpenAgentEmail なのか？

別々のターミナルやデバイスで動作するエージェントには、誰が作業を依頼し、誰が受け取り、何が起きていて、何が返ってきたかを共有する手段が必要です。作業をやり取りするためだけに、管理者の認証情報を共有したり、1つの実行環境に切り替えたりする必要はありません。

OAE は、一般的なメールと、構造化された認証済みのタスクスレッドを組み合わせます。エージェント用メールボックスとして、内容を確認できるタスク引き継ぎレイヤーとして、またはその両方として使用できます。メールと OTP のワークフローも引き続き第一級の機能です。このプロジェクトは、メールサービスの代替に限られるものではありません。

今日できること

これらは、管理された環境で撮影した実際の製品スクリーンショットです（匿名化済み）。 確認できるのは内容を検査できることまでであり、通知が受信されたことや、承認されたアクションが実行されたことを示すものではありません。

REST、HTTP MCP、stdio MCP ラッパーからこれらの操作を利用できます。オプションのタスク リースでは、宛先による確保、更新、解放ができますが、外部の副作用を 厳密に一度だけ発生させるものではありません。ツールリファレンスを参照してください。

クイックスタート

すでにインスタンスをお持ちですか？

運用担当者にご自身の ID アドレスと適切な ID トークンを確認してから、 エージェントを接続してください。別のメールサーバーをデプロイする必要はありません。 最初のタスク引き継ぎを完了するか、ご自身の ID にテストメールを 送信して、読み取れることを確認してください。

新しいインスタンスをデプロイする

ガイド付きセットアップを開始します。

npx -y @openagentemail/setup

セットアップ CLIで、デプロイとクライアント設定を進められます。 環境に合ったメールバックエンドを選択してください。

SSH トンネルまたは HTTPS リバースプロキシを意図的に設定する場合を除き、API は localhost にバインドしたままにしてください。メールの証明書と API の HTTPS は別々の要件です。 トークンを含む HTTP API をそのまま公開しないでください。

デプロイ後は、実際に選択した経路を検証してください。

同梱メールサーバー。 このスタックは mail.$DOMAIN、mail DKIM セレクター、 ポート 465/993 の TLS を管理します。この構成で doctor を実行してください。

sudo ./deploy/doctor.sh

同梱スタックの DNS、ポートアクセス、証明書、通知の前提条件を確認します。 ただし、IMAP/SMTP にログインしたり、往復メールを送信したりはしません。

API のみ（独自のメールプロバイダーを使用）。 deploy/doctor.sh は省略してください。 同梱のメールホストを前提としているため、異なる MX/DKIM 構成では誤ったエラーが報告されます。 代わりに、/healthz が healthy を返すこと、キャッチオールメールボックスの IMAP/SMTP 認証情報が機能することを確認し、実際に ID にメッセージを送信して読み戻してください。 その後で初めて、タスクのレシピを試してください。/healthz が healthy であることだけで証明されるのは、HTTP プロセスが稼働していることまでであり、メールが配信されることではありません。

既存の api-data ボリューム：root 以外のユーザーへの一度限りの移行（#93）

API ランタイムイメージは root ではなく、bun ユーザー（uid／gid 1000）として実行されます。 新しい名前付きボリュームは、イメージの /app/data ディレクトリから所有権を引き継ぐため、ホスト側での修正は不要です。API が root として実行されていた間に書き込まれた既存の本番ボリュームは root 所有のままです。新しい非 root プロセスは、一度移行するまでそこに書き込めません。

順番は、設計上、エラー時に即座に停止するようになっています。新しいイメージを展開する前に、ボリュームを移行してください。 先に新しいイメージを展開すると、所有権が修正されるまで起動を拒否するか、最初の書き込み時に失敗します。これは意図した動作であり、暗黙のフォールバックではありません。

1. プロジェクト固有のボリュームをバックアップします（プロジェクト名が openagentemail の場合の例は openagentemail_api-data です。API のみのスタックでは、-p／COMPOSE_PROJECT_NAME のプレフィックスを使用します。例：oae-alpha_api-data）。
2. ボリュームをマウントしている書き込み元を停止します（最低限、api サービスを停止してください。スタック全体の場合は、作業中に api-data に書き込むほかのサービスも停止します）。手順 6 で再作成するまで、停止した状態を保ってください。停止するだけでは不十分です。古いコンテナがすべて完全に削除されて初めて、移行が完了します。restart は再作成とは異なります。クラッシュ後に再起動した場合や、習慣的に再び起動した場合でも、戻ってきた root コンテナは書き込みを続け、エラーなしにボリューム上のファイルを root:root として再作成し、chown を元に戻してしまいます。何らかの理由で書き込み元が再び起動した場合は、停止してから、次に進む前に手順 3 をやり直してください。
3. ランタイムユーザーへの chown を一度だけ実行します。

# Replace <project>_api-data with your real volume name (docker volume ls).
docker run --rm -v <project>_api-data:/data alpine \
  sh -c 'chown -R 1000:1000 /data'

4. サービスを再起動する前に、所有権を抜き取り確認します。

docker run --rm -v <project>_api-data:/data alpine \
  sh -c 'ls -ln /data | head'
# Expect uid/gid columns to show 1000 / 1000 for migrated paths.

5. ボリュームへの移行結果を読み戻して確認します。成功する必要があります。

docker run --rm -v <project>_api-data:/data alpine \
  sh -c 'find /data ! -user 1000 | head'
# Expect no output: zero files still owned by a non-1000 user.

6. 新しいイメージをプル／ビルドし、何かを起動する前に、API イメージでランタイムユーザーが宣言されていることを確認します。プロジェクト全体をビルドしてください（サービス名を指定せずに docker compose build を実行します）。または、最低限 api と ntfy-provision をまとめてビルドしてください。両者は同じ Dockerfile を共有しており、以下の --force-recreate によって一度限りの ntfy-provision コンテナも再実行されるため、同じ非 root イメージのビルドから作成する必要があります。古い root ベースの provision イメージがここで再実行されると、ボリュームに root として書き込み、移行が元に戻ってしまいます。これは、この手順書で防ごうとしているのと同じ問題です。

docker inspect <new-api-image> --format '{{.Config.User}}'
# Expect bun (uid 1000) — never empty/root.

その後に限り、すべてを起動します（docker compose up -d --force-recreate または通常のデプロイ手順を使用してください）。

この順番を逆にしないでください。本番環境の chown はデプロイ作業時間内に行う操作であり、イメージのエントリーポイントでは実行されません。

デプロイ作業中の再作成に関する注意点（2026-09-21 に実測）

1. --force-recreate <service> は依存関係の連鎖に従います。 参照ホストでの実測では、api を再作成すると、api→mailserver→provision の依存関係に沿って mailserver も再作成されました（また、ntfy は ntfy-provision をプルします）。正常に動作し、所要時間は約 11 秒で、損失はありませんでしたが、意図した動作ではありませんでした。指定したサービスのみを再作成するには、--no-deps を追加してください。プロジェクト全体をビルドする場合は、通常の形式をそのまま使用できます。
2. 上書き設定の適用元を確認してください。推測で判断しないでください。 上書き設定を編集または削除する前に、次の3 つの構成に対して docker compose config を実行し、解決済みの出力を項目ごとに比較してください。ベース設定のみ、ベース設定と各上書き設定の組み合わせです。参照ホスト（2026-09-21）では、この確認により、同じ階層の 2 つのファイルを区別できました。docker-compose.override.yml は何も追加しない空の設定（パッチは以前にすべてベースファイルへ統合済み）であり、タイムスタンプ付きのバックアップを作成して削除されました。一方、compose.override.yaml は有効な設定であり、保持する必要があります（ループバックバインディングを追加し、許可ポートの範囲を広げます）。再作成時に「複数の上書きファイルが見つかりました」という警告が表示されたら、この確認を行ってください。適用範囲に関する注意：上書き設定の自動マージは、デフォルトファイルを使った実行時に限られます。ファイルを明示的に選択するデプロイ（例：API のみを対象とする docker compose -f compose.api-only.yaml ...）では、上書き設定は自動マージされないため、すべての上書き設定を明示的に渡す必要があります。

ntfy の非 root アップグレード（#278）

ntfy は UID 1000 で実行され、コンテナーのポート 2587 で待ち受けるようになりました。既存のデプロイで以前 ntfy を root として実行していた場合は、up -d の前にデータの所有者を変更してください。そうしないと ntfy の起動に失敗し、API が停止したままになります（depends_on のヘルスチェックが正常になるのを待ちます）。

# Same volume naming as above; only the ntfy subtree is required here.
docker run --rm -v <project>_api-data:/data alpine \
  sh -c 'chown -R 1000:1000 /data/ntfy'

次に docker compose up -d を実行します（ntfy と api を再作成します）。以前のフルボリュームの #93 移行で /data/ntfy はすでに対象になっています。このサブツリーがまだ root 所有の場合に限り、再実行してください。

エージェントを接続する

適切な認証情報を選ぶ

これらは現在の API の仕様であり、新しいスコープの提案ではありません。ID のすべての権限に管理者権限は含まれません。ID の作成、一覧表示、管理はオペレーターのみが行ってください。管理者キーをエージェントのクライアント設定に含めないでください。認証情報の設定を参照してください。

ローカル stdio MCP

公開されている MCP クライアントには Node.js 20 以降が必要です。これはパッケージの要件と一致しています。API サーバーはコンテナー内で Bun を実行します。一般的なローカルクライアントの設定は次のとおりです。

{
  "mcpServers": {
    "openagentemail": {
      "command": "npx",
      "args": ["-y", "@openagentemail/mcp"],
      "env": {
        "OPENAGENTEMAIL_API_URL": "http://localhost:3100",
        "OPENAGENTEMAIL_API_KEY": "oa_replace_with_your_identity_token"
      }
    }
  }
}

同じホスト上の API、またはローカル SSH トンネルの背後にある API にのみ localhost を使用してください。リモートインスタンスには HTTPS のベース URL を使用します。クライアント設定を保護し、トークンをコミットしないでください。stdio クライアントにメールサーバーの IMAP／SMTP 認証情報は必要ありません。

リモート HTTP MCP

リモート MCP に対応したクライアントは、stdio パッケージをインストールせずに、インスタンスの /mcp エンドポイントへ直接接続できます。公開 HTTPS オリジンを設定し、クライアントがサポートする Bearer／OAuth フローに従ってください。OAuth による許可には、管理者認証情報や直接の ID 認証情報と同じ変更権限はありません。クライアントガイドを参照してください。プロトコルへの対応は、自動ウェイクアップやベンダー提携を意味するものではありません。

MCP リファレンスでは、登録済みツール、権限、待機の仕様をすべて説明しています。各サーバーの待機時間には MCP_MAX_WAIT_SECONDS による上限があります（デフォルトは 60 秒で、1～600 秒に設定できます）。MCP メールクライアントは、要求された合計期限内で短い待機区間を再設定できます。タスクの待機は上限付きの 1 回のターンです。待機のタイムアウトはジョブの失敗を意味しません。作成結果が不確かな場合は、むやみにタスクを再作成せず、返されたタスク ID／履歴を確認してください。

仕組み

flowchart TB
    Agents["Existing agents / harnesses"] -->|"REST · HTTP MCP · OAuth"| API["OAE API: Bun + Hono"]
    Agents --> Stdio["Node stdio MCP wrapper"]
    Stdio -->|"REST"| API
    Human["Humans via /ui"] --> API
    API -->|"SMTP / IMAP"| Mail["Bundled mailserver or external catch-all"]
    API --> State["DATA_DIR local state<br/>identities · auth · sessions · webhooks<br/>optional lease journal"]
    Mail -->|"IMAP"| Watcher["Watcher in the API process"]
    Watcher --> Delivery["ntfy and/or webhook delivery"]
    Delivery --> Adapter["External adapter / receiver"]
    Adapter -. "Activation is integration-specific" .-> Agents

タスクは、認証済みメール記録から再構成されます。ローカルファイルには、任意の保留中リースジャーナルを含む運用状態も保存されます。実行はエージェント自身のランタイム内で行われます。OAE がモデルを実行することはありません。これはバックグラウンドループを備えた単一プロセスのサービスであり、分散ワーカーのランタイムではありません。

コアは Orca を必要としません。リポジトリに含まれるウェイクアップ用 Webhook の例は現在 Orca を対象としています。これは汎用の置き換えアダプターではありません。すでに記録済みの保留中の Webhook 配信は復旧できますが、API の停止中に届いたすべてのメールをウォッチャーが再生するわけではありません。通知だけを作業記録として扱わず、コンシューマーは起動時または再接続時にタスク／メールの状態を照合してください。

SMTP／IMAP の可視性オーバーレイ、タスク状態、通知の境界については、現在のアーキテクチャとデータの所有権をお読みください。

デプロイと境界

サーバーだけでなく、データ経路も管理してください。 セルフホスト可能なインスタンスを使えば、必須の OAE SaaS コントロールプレーンを回避できます。一方、外部のメールボックスプロバイダー、SMTP リレー、アーカイブの宛先、通知先には、設定に応じて引き続きデータが送信される可能性があります。リモートモデル／クライアントに返されるメールもサーバーの外に出ます。認証情報やメッセージの内容を公開する前に、その経路を確認してください。

容量と制限は運用上の選択です。 ID ごとのソフトウェアライセンス料はありません。それでも、メールボックスの容量、プロバイダーのポリシー、ディスク、メモリ、設定可能なレート制限は適用されます（送信の既定値は ID ごとに 1 時間あたり 20 件です。API は起動時に send-log.jsonl からその時間単位のウィンドウを再構築します。対象はキューに入った行と、SMTP サーバーが応答した失敗行です。ログ行が失われた送信はカウントされません）。 通常のメールの既定の保持期間は 30 日です。タスクマーク付きのメールは、この定期削除の対象外です。メールストア、DATA_DIR、安定した署名シークレットは、まとめてバックアップしてください。

既読状態は共有されます。 メッセージを既読にすると、他のメールボックス利用者にも影響します。これはエージェント固有の確認ではありません。独立して処理するには、利用者ごとのカーソルと定期的な照合を使用してください。読むだけではメールは既読になりません。

フレームワークの例やローカルのフィクスチャは、本番環境でエンドツーエンドの 実行が行われた証拠ではありません。それぞれの README で、どの経路が偽の サービスを使用し、どの経路が明示的な実環境での呼び出しを必要とするかを 説明しています。

今後の方針と貢献

独自のエージェントを持ち込み、作業を検証可能に保ち、インフラを自分で管理しましょう。 別のランタイムではなく、引き継ぎを構築しましょう。

今後は、既存の作業環境への接続を簡素化し、復旧や運用に関するガイダンスを 明確にしていきます。汎用スケジューラー、共有ワークスペースマネージャー、 グローバルなフェデレーション、自動コード実行を約束するものではありません。 現在の機能は上記に記載しています。リリース履歴は CHANGELOG.mdを参照してください。npm バッジが示すのは MCP パッケージの情報であり、サーバー／デプロイ全体の統一バージョンではありません。

README の更新と、残っているライブデモ／ウェブサイト関連の対応については #251を参照してください。 公開サイトの表示とドキュメントは ウェブサイトのリポジトリが管理しています。

Issue と PR を歓迎します。CONTRIBUTING.mdをお読みください。 大規模な作業は Issue から始め、マージ前に独立したレビューと CI の成功が必要です。 ドキュメントの変更は、予想される機能ではなく実際のコードに沿ったものにしてください。

mkdir -p ../oae-api-only-env
cp .env.api-only.example ../oae-api-only-env/alpha.env
cp .env.api-only.example ../oae-api-only-env/beta.env
chmod 600 ../oae-api-only-env/*.env
# Set API_PORT=3100 in alpha.env and API_PORT=3101 in beta.env.
# Generate separate API_KEYS and TASK_SIGNING_SECRET values in each file.

docker compose -p oae-alpha --env-file ../oae-api-only-env/alpha.env -f compose.api-only.yaml up -d
docker compose -p oae-beta --env-file ../oae-api-only-env/beta.env -f compose.api-only.yaml up -d

localhost、SSH トンネル、または HTTPS 経由で /ui を開き、適切なトークンでログインしてください。通常のセッションと、永続化される このデバイスを信頼する セッションでは有効期間が異なります。API を再起動しても、信頼済みのセッションがすべて破棄されるわけではありません。UI アクセスとセッションを参照してください。 ダッシュボード UI は、設定の言語セレクター（oa_lang cookie）から en / es / ja / ko / zh-CN を選択できます。用語はdocs/i18n-glossary.mdに準拠しています。

概要の件数は、全期間の合計ではなく、上限のある期間の集計です。キャッシュのタイミング、不明な件数、スキャン上限については、運用ガイドで説明しています。

複数ドメインのサポート

DOMAIN と EXTRA_DOMAINS で、1 つのインスタンスが管理するドメインを定義します。同じローカルパートを持つ明示的な ID は、設定済みの異なるドメインで共存できますが、完全に同一のアドレスは重複できません。追加ドメインには、引き続きプロバイダー／MTA のルーティングと DNS／DKIM の設定が必要です。これは独立したインスタンス間のフェデレーションではありません。複数ドメインの運用を参照してください。

パブリックメールの TLS と更新はオプトインです。API の HTTPS には、独自の信頼できるリバースプロキシまたはトンネルが必要です。

オプションのコンプライアンスアーカイブ： ALWAYS_BCC はデフォルトでオフであり、ドメイン外のデータ受信者が追加されます。

デプロイ、データパス、ポリシーを管理するためにセルフホストしてください。コストがゼロになること、ハードウェア容量が無制限であること、上流プロバイダーのポリシーの影響を受けないことを保証するものではありません。

リソース計画はワークロードによって異なります。この README では、日付のないベンチマークや VPS 価格の保証を掲載していません。

OAE は、エージェントのメールとタスクの引き継ぎに対応するオープンソースの選択肢です。ベンダーとの詳細な比較には、日付が明記された一次資料が必要です。以前の未検証の機能比較表は廃止されました。

ドキュメント一覧。

ライセンス

Apache-2.0。