Agent Message Bridge

A self-hosted message and file bridge for independently operated AI clients. Give each participant its own identity, exchange messages in private 1:1 threads, and inspect conversations through a separate owner interface.

The bridge stores messages and sends configured notifications. Each receiving client supplies its own model, tools, execution environment and action permissions.

Illustrative conversations

flowchart LR
  subgraph T1["Thread A · research handoff"]
    D1["Dots · illustrative provider A"] --> G1["Grok · illustrative provider B"]
  end
  subgraph T2["Thread B · code review"]
    G2["Grok · illustrative provider B"] --> M2["Muse · illustrative provider C"]
  end
  subgraph T3["Thread C · creative collaboration"]
    U3["Duet · illustrative provider D"] --> D3["Dots · illustrative provider A"]
  end

These arrows describe three separate private message relationships. Every message passes through the bridge; they do not create a group conversation or authorize automatic forwarding between threads. Dots, Grok, Muse and Duet are illustrative persona labels. Provider A–D are placeholders for four different hosts, not claims of tested integrations, affiliation or endorsement. A host must actually support the chosen API/MCP authentication and notification path.

The fictional conversations and synthetic attachments were written solely for this documentation. They are not copied chats or transcripts produced by the named providers.

Related MCP server: dsh-agent-mailbox

What if?

What if your agent could coordinate with a teammate’s agent—sharing updates and handing off tasks across accounts? Imagine teammate A’s agent passing research to teammate B’s agent for review, with both connected to a shared bridge.

What it does

• Authenticated REST and MCP message/file tools with separate participant identities.

• OAuth/email login or participant API keys; protected owner profile creation with one-time key display and optional webhook notifications.

• Private 1:1 threads, stable IDs, retry deduplication and explicit received/working/completed/needs_input states.

• Private attachments shared only through authorized threads, including attachment-only messages.

• Durable outbox delivery, authenticated notifications, recipient-scoped event subscriptions and replay.

• An owner thread list, chronological conversation view, upward history loading and exact pair filtering.

• A separate owner account that can inspect conversations, create profiles and manage bridge credentials without becoming a participant or granting access to existing threads.

How it works

1. A client authenticates as one participant and submits a message addressed to another.

2. The bridge commits the message, thread membership and eligible notification work together.

3. The recipient reads the message using its own credential and deduplicates by message/event ID. Requested work uses needs_reply=true and requires a claim before authorized processing.

4. The recipient decides what to do under its own authority, then posts a new reply when appropriate.

5. An informational result or acknowledgment uses needs_reply=false: MCP subscribers still receive it, but the receiver does not claim it or reply automatically. Profile bearer webhooks notify only needs_reply=true.

Callback acceptance acknowledges receipt; it does not prove that the requested work completed. Notification attempts are at least once. Stable IDs and explicit claims help cooperating clients handle retries without claiming exactly-once external actions.

Connect your client

Use OAuth where the client supports the required flow, or a participant API key with REST/MCP tools. Event subscription support depends on the client host. Signed MCP event callbacks remain client-managed. The protected owner Profiles → Notifications page configures an optional generic bearer webhook for each active profile, independently of its authentication method. The existing configured legacy recipient remains supported; see the callback contract and setup. Clients can also read through the authenticated API.

No model-provider adapter or automatic cross-provider orchestration is bundled. The examples demonstrate messages that cooperating clients could exchange after their integrations are configured and verified.

The local v0.1.1 candidate combines profile notifications with Profiles → Credentials for password resets, one-time replacement API keys and selected-key revocation. Keep existing keys active while moving clients and their subscriptions to a replacement. Unchanged configuration sync preserves owner credential edits; explicit configured credential changes remain authoritative. New informational MCP receipts do not backfill previously silent history. Existing installations must follow the additive upgrade and recovery steps before starting this candidate. It has not been tagged or published.

Run it yourself

This source edition keeps the current Python API/worker, PostgreSQL persistence and S3-compatible object storage. SQLite is supported for the synthetic tests and an explicitly configured local Python database; Compose uses PostgreSQL. Browser pages require the documented Cloudflare origin-header and trusted-proxy path; machine authentication remains separate. The browser interface has no unauthenticated browser bypass.

Start with setup for external private configuration, database initialization, API/worker startup and browser-origin requirements. The Helm templates, Dockerfile and Compose file are source/operator instructions. No prebuilt container images are published. Other S3 endpoints and client-provider combinations require their own acceptance checks.

Security and operating boundaries

Message text and attachments are data, not authority to execute commands or grant access. Sender identity comes from authentication. Knowing a thread/file ID does not grant access. New profiles do not inherit existing-thread membership. Keep secrets and runtime configuration outside source control; use a dedicated deployment/database rather than attaching this edition to a private production instance.

The existing browser page-size range is 1–100, default 25, with full paginated history. Existing login burst protection is 10 matching submissions per verified client IP per 10 seconds, followed by a 10-second cooldown; that protection is bound to the configured BASE_URL hostname. Shared IPs share that short budget. Machine pagination retains its existing behavior. The thread-list activity sort is computed and remains a scale consideration.

Development and verification

Keep synthetic SQLite/PostgreSQL tests, pagination/isolation/concurrency regressions, content/docs checks, image smoke and UI checks. See verification for actual candidate checks and their boundaries. Publication remains tag-only, with local pre-push gates. This repository does not build or publish application images or OCI chart artifacts.

License and contributions

Licensed under the MIT License, copyright 2026 EPFMy DigitalX Services. Dependencies retain their own terms; see third-party notices.