Skip to main content
Glama

A covalent bond is two atoms sharing a pair of electrons. Covalent Bond is two coding agents on different machines sharing something just as fundamental: a private, authenticated channel, and through it, a way of working.

Picture two developers pairing across a distance. One has their agent dialed in (organized skills, sharp conventions, the right context loaded) and it produces excellent work. The other is more ad-hoc, and their agent turns out something that's just okay. Covalent Bond is the channel that closes that gap: the well-tuned side can hand over the files, context, and conventions that make its agent good, so both agents converge on the same high-quality way of working. It bonds not just two agents, but two ways of working, pulling the weaker setup up to the level of the stronger, as equal peers.

It's peer-to-peer and end-to-end encrypted: the two agents pair up and exchange messages and files through a relay that can never read the traffic. It works with any MCP-compatible agent (Claude Code, Cursor, Codex, Windsurf, Cline, and others), exposing bond_* tools over the Model Context Protocol. And it keeps a human in the loop: every incoming file waits for explicit consent before it touches disk.

  • 🤝 Bonds two ways of working: share files, context, and conventions so both agents level up together

  • 🔒 Authenticated E2EE: a malicious relay can't read or MITM the channel

  • 🌐 Cross-machine: pair agents anywhere, through a dumb relay (no inbound ports)

  • 🙋 Human-in-the-loop: consent before any file is written; full audit log

  • 🔌 Agent-agnostic: any MCP client, not tied to one vendor

It doesn't magically clone one setup onto another. It's the secure, consent-gated channel that makes deliberately sharing your working style possible between two machines that otherwise can't reach each other.

Quick start

Shortcut: let your agent set everything up. Paste docs/AGENT-SETUP.md to any coding agent and say "set up Covalent Bond". It walks the agent through install, relay config, MCP registration, and pairing, with clear stops for the parts only a human may do.

Or do it yourself on both machines (steps 1–2), then pair (step 3).

  1. Register the MCP server with your agent — no install needed, npx fetches the npm package. For Claude Code:

    claude mcp add --scope user --env COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev covalent -- npx -y covalent-bond

    (--scope user makes the bond_* tools available in every project. The env var points at the public relay; to self-host instead, see Pick a relay.)

    For other MCP clients (Cursor, Codex, Windsurf, …), this standard stdio-server config works in most of them; paste it into the client's MCP settings JSON (the top-level key is usually mcpServers or servers):

    {
      "mcpServers": {
        "covalent": {
          "command": "npx",
          "args": ["-y", "covalent-bond"],
          "env": {
            "COVALENT_RELAY_URL": "https://covalent-bond-relay.gopalrajsuresh.workers.dev"
          }
        }
      }
    }

    On Windows, if your client struggles to spawn npx directly, wrap it: "command": "cmd", "args": ["/c", "npx", "-y", "covalent-bond"]. For local testing without a deployed relay, run the mock relay from a source checkout (npm run relay:dev) and point COVALENT_RELAY_URL at http://localhost:8787.

    git clone https://github.com/gopalrajsuresh/covalent-bond.git covalent-bond
    cd covalent-bond
    npm install
    npm test                    # optional but recommended; all suites run offline
    cp .env.example .env        # PowerShell: Copy-Item .env.example .env

    The .env already contains the public relay URL. Then register with command: node, args /absolute/path/to/covalent-bond/bin/cli.js (Claude Code: claude mcp add --scope user covalent -- node /absolute/path/to/covalent-bond/bin/cli.js), no env var needed.

  2. Restart your agent session, then verify: ask the agent to run bond_status. It should reply "No active session", which means the tools are live.

  3. Pair and share

    • Machine A: "Create a Covalent Bond session" → agent runs bond_connect → you get a code like AbCd-1234-XyZw.

    • Tell the code to the other human out-of-band (chat or voice, never through the relay).

    • Machine B: "Join Covalent Bond session AbCd-1234-XyZw" → agent runs bond_join.

    • Either side: bond_status → Secure channel established → send files (bond_send) and messages (bond_message). Incoming files wait for the human to bond_accept.

    • Done? bond_end on both sides.

Related MCP server: Session Multiplayer

How it works

Both agents meet at a relay that is untrusted by design — it forwards ciphertext it can never decrypt. The session code travels human-to-human, never through the relay, and that out-of-band secret is what authenticates the channel:

sequenceDiagram
    participant A as Agent A (host)
    participant H as Humans (out-of-band)
    participant R as Relay (untrusted)
    participant B as Agent B (guest)

    A->>A: bond_connect → session code
    A-->>H: code shared by chat / voice
    H-->>B: code entered on the other side
    B->>B: bond_join(code)
    A->>R: ephemeral public key (routing ID only)
    B->>R: ephemeral public key (routing ID only)
    Note over A,B: key = X25519 ⊕ session code → AES-256-GCM
    A->>R: ciphertext
    R->>B: ciphertext (relay sees nothing else)
    B->>B: file held until human runs bond_accept

If anything in the middle tampers with the key exchange, key confirmation fails and the session aborts before any data flows — a malicious relay can't read or impersonate either side.

Pick a relay

The relay is a dumb pipe and untrusted by design: it sees only a random routing ID and ciphertext, never the session code, keys, or plaintext, and a malicious relay still can't read or forge anything (that's covered by the test suite's MITM scenario). So either option below is equally secure; it's purely a convenience choice.

Option 1: use the public relay (fastest)

COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev

Sessions expire after 30 minutes of inactivity and nothing is retained. Best-effort availability, rate-limited.

  • .env file (simplest): copy .env.example to .env in the covalent-bond folder and edit the value. The MCP server reads it at startup, so it applies no matter which project you use the agent from.

  • MCP client config: pass it when registering the server, e.g. for Claude Code:

    claude mcp add --scope user --env COVALENT_RELAY_URL=https://... covalent -- node /absolute/path/to/covalent-bond/bin/cli.js

    For other MCP clients, add it to the server's env block in their JSON config.

After changing either, restart your agent session so the MCP server relaunches.

Option 2: deploy your own in ~2 minutes (free Cloudflare account)

npm install -g wrangler
wrangler login          # opens the browser; create a free account if you don't have one
cd cloudflare-worker
wrangler deploy         # prints your relay URL: https://covalent-bond-relay.<your-subdomain>.workers.dev

Then set COVALENT_RELAY_URL to that URL on both machines. Full details (Durable Object migration, optional per-IP throttle, local wrangler dev) are in cloudflare-worker/README.md.

Paste this to any coding agent running in this repo:

Deploy my own Covalent Bond relay: install wrangler if missing, run wrangler login and wait for me to finish authenticating in the browser, then wrangler deploy from cloudflare-worker/, and tell me the URL to set as COVALENT_RELAY_URL on both machines. Follow cloudflare-worker/README.md.

The only manual step is the browser login; the agent handles the rest.

Pair two agents

  1. Machine A: "Create a Covalent Bond session." → the agent calls bond_connect and returns a code like AbCd-1234-XyZw.

  2. Share that code with Machine B out-of-band (chat, voice, in person). It's the secret that secures the link. Never paste it into the relay.

  3. Machine B: "Join Covalent Bond session AbCd-1234-XyZw." → the agent calls bond_join.

  4. When bond_status shows Secure channel established, start sharing: "Send src/auth.js to my peer," or hand over the pieces that make your agent good: a skill file, a conventions doc, the context that shapes how it works. The peer sees a consent prompt and accepts before anything is written, and the received content arrives wrapped as untrusted data for the other agent to read and adopt.

Tools

  • bond_connect — Create a session and get a shareable session code

  • bond_join — Join a session using a code shared out-of-band

  • bond_status — Connection status, pending transfers, and new events

  • bond_send — Send a file to the connected peer, encrypted end to end

  • bond_message — Send a short encrypted text message to the peer

  • bond_wait — Long-poll for the next peer event

  • bond_accept — Accept a pending file transfer after human consent

  • bond_decline — Decline a pending file transfer

  • bond_end — End the session and disconnect from the relay

Full reference:

Tool

Parameters

What it does

Requires

bond_connect

—

Create a session as host; returns the code to share out-of-band

—

bond_join

sessionCode

Join a session with a code (XXXX-XXXX-XXXX, Base58)

—

bond_status

—

Handshake state, pending transfers, unread-event count, and events since the last call

—

bond_send

filepath, message?

Send a file (type whitelist, size cap, 10 s rate limit) with an optional context message

confirmed channel

bond_message

content

Send a short encrypted text message, max 4000 chars (agent-to-agent conversation)

confirmed channel

bond_wait

timeoutSeconds?

Long-poll for the next peer event (message, file, disconnect); default 50 s, max 300 s

confirmed channel

bond_accept

transferId

Write a pending file to ~/.covalent/incoming/ and return its content wrapped as untrusted data

human consent

bond_decline

transferId

Discard a pending transfer (the sender is not notified)

human consent

bond_end

—

Disconnect and clear session state, including pending transfers

—

? marks an optional parameter. confirmed channel means the tool refuses to run until key confirmation has succeeded on both sides; human consent means the agent may only call it after the human explicitly decides on the pending transfer.

Incoming events raise a desktop notification (disable with COVALENT_NOTIFICATIONS=off). File size defaults to 256 KB, overridable via COVALENT_MAX_FILE_KB (up to 384 KB, bounded by the relay's wire limit).

Security

Each session is secured by two secrets: ephemeral X25519 keys exchanged through the relay, and a short session code the two humans share out-of-band. The code is mixed into the encryption key but never sent to the relay, so a relay that tampers with the key exchange (a MITM) can't derive the key, key confirmation fails, and the session aborts before any data flows. The relay only ever sees a routing ID, public keys, and AES-256-GCM ciphertext. Every incoming file waits for explicit human consent, and every operation is logged.

Full details, threat model, and handshake diagram: docs/ARCHITECTURE.md.

Share the session code over a channel the relay operator doesn't control. That out-of-band step is what makes the channel authenticated, not just encrypted.

Testing

npm test          # all suites, via test/run-all.js, against an in-process mock relay

No network or wrangler needed. The suite covers the key schedule, the full handshake and file transfer, two MCP servers end-to-end, a simulated malicious relay (mitm), and the relay's hardening. See docs/ARCHITECTURE.md for the breakdown, and docs/TWO-MACHINE-TEST.md for a real two-machine run.

Deploying the relay

The relay is a Cloudflare Worker in cloudflare-worker/ with one Durable Object per session. It stores only routing IDs, public keys, and ciphertext, expiring 30 minutes after the last activity. It can't decrypt anything.

Status

Authenticated E2EE, MCP integration wired end-to-end, full test suite green. Pre-1.0: the protocol and API may still change.

Contributing & security reports

Contributions are welcome. Start with CONTRIBUTING.md, which includes the security invariants and the branch/PR workflow. To report a vulnerability, please use the private process in SECURITY.md, not a public issue.

License

MIT; see LICENSE.


Available Tools

5 tools
bond_acceptA

Accept a pending file transfer. File will be written to ~/.covalent/incoming/ and its content returned, wrapped in untrusted-data markers.

Inputs: transferId (required).

bond_declineA

Decline a pending file transfer. File will be discarded and sender will not be notified.

Inputs: transferId (required).

bond_endA

End the current Covalent Bond session and disconnect from relay. Clears all pending transfers.

Inputs: no named parameters.

bond_joinA

Join an existing Covalent Bond session using a session code (format: XXXX-XXXX-XXXX Base58, e.g., "3KPz-QR7m-8WXn"). Call this when the user provides a session code from another agent. The code is a shared secret - it authenticates the encrypted channel and is never sent to the relay.

Inputs: sessionCode (required).

bond_sendA

Send a file to the connected agent. File will be encrypted and delivered with an optional message. Subject to 10-second rate limit and security validation (file type whitelist, 256KB default size limit, configurable via COVALENT_MAX_FILE_KB).

Inputs: filepath (required), message.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: joining a session, sending a file, accepting/declining a transfer, and ending the session. No overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent 'bond_verb' pattern (e.g., bond_join, bond_send), making it predictable and easy to understand.

    Tool Count5/5

    With 5 tools, the server covers the essential operations for a file transfer session without being excessive or sparse.

    Completeness4/5

    The set covers the core session lifecycle (join, send, accept/decline, end), but lacks a tool to create a new session or view pending transfers, which are minor gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables two coding agents on separate machines to communicate directly via a private git repo, with end-to-end encryption and no server required. Provides tools for joining rooms, sending/receiving messages, and managing side channels.
      60
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI coding agents in different harnesses, projects, or machines to share encrypted peer-to-peer rooms and exchange messages directly, without any central server or account.
      8
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to communicate directly with each other across machines, with support for rooms, pairing, and encrypted messaging.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables a coding agent to ask another person's coding agent questions across different machines, networks, and subscriptions, with revocable directional permission and a locked-down responder session enforced by configuration.
      MIT