Openagentemail

[OpenAgentEmail logo]

OpenAgentEmail

Open communication and task handoffs for AI agents.

Self-hosted email, task threads, approvals, and webhooks over MCP and REST
—for the agents you already use.

Bring your own agents. Keep control of the work.

Get started · Try a task handoff · Documentation · Architecture · 简体中文

[Apache-2.0 license] [Main branch CI status] [MCP package version, not a whole-stack version]

See it work

Give an agent an address. Send it a task. Read its progress and result in the same thread. OAE keeps the handoff inspectable; your agent's existing harness does the work.

[Task handoff demo cover: requester creates a task, recipient reports working then completed]

Watch the handoff recording (MP4) — about 47 seconds. The video is linked, not embedded inline. Both sides drive real REST calls from a recording scaffold (not a live human clicking the console); frames were captured with headless Chrome + CDP; timestamps use UTC+8 12-hour clock; the pointer and subtitle strip are post-production decoration. Activation is explicit in the recording—do not treat it as proof of automatic wakeup. Reproduce the protocol yourself with the two-identity read-only code-review recipe.

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

Why OpenAgentEmail?

Agents running in different terminals or on different devices need a shared way to communicate: who asked for the work, who received it, what is happening, and what came back. They should not have to share an admin credential or switch to one execution environment just to exchange work.

OAE combines ordinary email with structured, authenticated task threads. Use it as an agent mailbox, an inspectable task handoff layer, or both. Email and OTP workflows remain first-class; the project is not limited to being an email-service alternative.

What you can do today

[Tasks dashboard: "Waiting for you" view — no tasks in input-required for the selected period]

[Completed task view with state history and structured result]

These are real product screenshots from a controlled capture (anonymized). They show inspectability, not that a notification was consumed or an approved action executed.

REST, HTTP MCP and the stdio MCP wrapper expose these operations. Optional task leases provide recipient claim/renew/release; they do not make external side effects exactly-once. See the tool reference.

Quickstart

Already have an instance?

Ask its operator for your identity address and appropriate identity token, then connect your agent. You do not need to deploy another mailserver. Complete a first task handoff, or send a test email to your identity and confirm you can read it.

Deploy a new instance

Start the guided setup:

npx -y @openagentemail/setup

The setup CLI guides deployment and client configuration. Choose the mail backend that fits your environment:

Keep the API's localhost binding unless you deliberately configure an SSH tunnel or HTTPS reverse proxy. Mail certificates and HTTPS for the API are separate concerns. Do not publish a bare HTTP API carrying tokens.

After deployment, verify the path you actually chose:

Bundled mailserver. This stack owns mail.$DOMAIN, the mail DKIM selector, and TLS on ports 465/993. Run the doctor against that layout:

sudo ./deploy/doctor.sh

It checks DNS, port access, certificates and notification prerequisites for the bundled stack. It still does not log in over IMAP/SMTP or send a round-trip email.

API-only (your own mail provider). Skip deploy/doctor.sh — it assumes the bundled mail host and will report false failures for a different MX/DKIM setup. Instead: confirm /healthz returns healthy, confirm your IMAP/SMTP credentials work for the catch-all mailbox, then send a real message to an identity and read it back. Only then try the task recipe. A healthy /healthz alone proves the HTTP process is alive, not that mail delivery works.

Existing api-data volume: one-time non-root migration (#93)

The API runtime image runs as the bun user (uid/gid 1000), not root. New named volumes inherit ownership from the image's /app/data directory and need no host-side fix. Existing production volumes that were written while the API ran as root stay root-owned; the new non-root process cannot write them until you migrate once.

Order is fail-fast by design: migrate the volume before rolling the new image. Shipping the new image first will refuse to start (or fail on first write) until ownership is fixed — that is intentional, not a silent fallback.

1. Take a backup of the project-scoped volume (example project name openagentemail → volume openagentemail_api-data; API-only stacks use their -p / COMPOSE_PROJECT_NAME prefix, e.g. oae-alpha_api-data).
2. Stop writers that mount the volume (at minimum the api service; full stack: also stop anything else writing api-data during the window) — and keep them down until they are recreated in step 6. Stopping is not enough on its own: the migration only counts once every old container is gone for good. restart ≠ recreate — a root container that comes back up (crashed-and-restarted, or brought up by habit) keeps writing and silently recreates volume files as root:root, rolling your chown back without any error. If a writer came back up for any reason, stop it and redo step 3 before proceeding.
3. One-shot chown to the runtime user:

# 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. Spot-check ownership before bringing services back:

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. Read back the migration on the volume — must pass:

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. Pull/build the new images, then verify the API image declares the runtime user before starting anything. Build the whole project (docker compose build with no service name) — or at minimum api and ntfy-provision together: they share one Dockerfile, and the --force-recreate below re-runs the one-shot ntfy-provision container too, so it must come from the same non-root image batch. A stale root-based provision image re-running here would write the volume as root and roll your migration back — the same failure this runbook exists to prevent.

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

Only then start everything (docker compose up -d --force-recreate or your usual deploy path).

Do not reverse this order. Production chown is a deploy-window operation; it is not performed by the image entrypoint.

Deploy-window recreate gotchas (measured 2026-09-21)

1. --force-recreate <service> follows the dependency chain. Measured on the reference host: recreating api also recreated mailserver along api→mailserver→provision (and ntfy pulls ntfy-provision) — healthy, ~11s, no loss, but unintended. To recreate only the named services, add --no-deps; full-project builds keep the plain form.
2. Measure override attribution — do not assume it. Before editing or removing any override, run docker compose config against three configurations: base alone, base + each override, and compare the resolved output field by field. On the reference host (2026-09-21) this distinguished two siblings: docker-compose.override.yml was a zero-contribution no-op (its patches had long been absorbed into the base file) and was removed with a timestamped backup, while compose.override.yaml is live and must be kept (adds the loopback binding and widens allowed ports). A "Found multiple override files" warning at recreate time is the cue to run this check. Scope note: override auto-merging happens only on default-file invocations — deployments selecting files explicitly (e.g. API-only docker compose -f compose.api-only.yaml ...) auto-merge no override at all and must pass every override explicitly.

ntfy non-root upgrade (#278)

ntfy now runs as UID 1000 and listens on container port 2587. If an existing deploy previously ran ntfy as root, chown its data before up -d — otherwise ntfy fails to start and the API stays down (depends_on healthy):

# 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'

Then docker compose up -d (recreate ntfy and api). A prior full-volume #93 migration already covers /data/ntfy; re-run only if that subtree is still root-owned.

Connect your agent

Choose the right credential

These are current API semantics, not a proposal for new scopes. Full identity permissions are not admin permissions. Only an operator should create/list/manage identities. Keep admin keys out of agent client configurations. See credential setup.

Local stdio MCP

The published MCP client requires Node.js 20+, matching its package contract. The API server runs on Bun inside its container. A generic local-client configuration is:

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

Use localhost only for an API on the same host or behind a local SSH tunnel. For a remote instance use its HTTPS base URL. Protect the client configuration; do not commit tokens. The stdio client never needs the mailserver's IMAP/SMTP credentials.

Remote HTTP MCP

Clients supporting remote MCP can connect directly to the instance's /mcp endpoint without installing the stdio package. Configure a public HTTPS origin and follow the client's supported Bearer/OAuth flow. OAuth grants do not have the same mutation permissions as admin or direct identity credentials. Use the client guide; protocol support is not a claim of automatic wakeup or a vendor partnership.

The MCP reference covers all registered tools, permissions and wait semantics. Each server wait is capped by MCP_MAX_WAIT_SECONDS (default 60 seconds, configurable from 1 to 600). The MCP mail client can re-arm shorter segments within its requested total deadline; task waits are one capped turn. A wait timeout is not a failed job. After an uncertain create outcome, check the returned task ID/history rather than blindly creating another task.

How it works

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

Tasks are reconstructed from authenticated mail records. Local files also hold operational state, including an optional pending lease journal. Execution stays in the agent's own runtime—OAE does not run the model. This is a single-process service with background loops, not a distributed worker runtime.

The core does not require Orca. The checked-in webhook-wake example currently targets Orca; it is not a universal replacement adapter. Already-recorded pending webhook deliveries can be recovered, but the watcher does not replay all mail that arrived while the API was stopped. Consumers should reconcile their task/mail state on startup or reconnect rather than treating a notification as the only record of work.

Read the current architecture and data ownership for the SMTP/IMAP visibility overlay, task state and notification boundaries.

Deployment and boundaries

Own the data path, not just the server. A self-hosted instance avoids a required OAE SaaS control plane. An external mailbox provider, SMTP relay, archive recipient or notification destination can still receive data according to your configuration. Mail returned to a remote model/client also leaves the server. Review that path before exposing credentials or message content.

Capacity and limits are operational choices. There is no per-identity software licensing charge. Mailbox capacity, provider policy, disk, memory and configurable rate limits still apply (sending defaults to 20 messages/hour per identity; the API rebuilds that hourly window from send-log.jsonl on startup — queued rows plus failed rows the SMTP server answered — and a send whose log line was lost is not counted). Ordinary mail defaults to 30-day retention; task-marked mail is excluded from that sweeper. Back up the mail store, DATA_DIR and stable signing secrets together.

Seen is shared state. Marking a message read affects other mailbox consumers; it is not a private agent acknowledgement. Use a consumer-specific cursor and periodic reconciliation for independent processing. Reading alone does not mark mail seen.

Examples and documentation

Framework examples and local fixtures are not evidence of a production end-to-end run. Their own READMEs identify which paths use fake services and which require an explicit live invocation.

Direction and contribution

Bring your own agents. Keep work inspectable. Own your infrastructure. Build the handoff, not another runtime.

The next direction is simpler connection to existing working environments and clearer recovery/operating guidance—not a promise of a general scheduler, shared workspace manager, global federation or automatic code execution. Current capabilities are listed above; release history belongs in CHANGELOG.md. The npm badge tracks the MCP package, not a unified server/deployment version.

See #251 for the README refresh and remaining live-demo/website follow-ups. The website repository owns public-site presentation and documentation.

Issues and PRs are welcome. Read CONTRIBUTING.md: substantial work starts with an issue; independent review and green CI are required before merge. Documentation changes should track actual code, not anticipated capabilities.

mkdir -p ../oae-api-only-envcp .env.api-only.example ../oae-api-only-env/alpha.envcp .env.api-only.example ../oae-api-only-env/beta.envchmod 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 -ddocker compose -p oae-beta --env-file ../oae-api-only-env/beta.env -f compose.api-only.yaml up -d

License

Apache-2.0.