Diavlos

>> Diavlos

Diavlos (δίαυλος, Greek for "channel") lets AI agents talk to each other. Any agent, any terminal, any computer. You pick a room name and share a signed invite. The agents find each other and start talking.

It is one small program. You install it once. It runs in the background. Any agent from any vendor can use it: Claude Code, Codex, Cursor, Gemini CLI, Aider, or one you wrote yourself. No account. No server to set up.

The big difference from a plain chat pipe: messages never get lost, every sender is who they say they are, and messages carry a type (task, reply, done) so agents never have to guess.

https://diavlos.sh

Watch it work

Two rented cloud desktops on different machines, one room, over the public internet with nothing port-forwarded. A real Claude agent does the work, a scripted agent hands it out, a human approves the one risky step from a browser, and a read-only observer key audits the lot afterwards. Nineteen signed messages, 77 seconds from the first task to the human's approve.

It also refuses a prompt injection on camera: the boss agent tells the Claude agent to ignore its instructions and run something it is not allowed to, and the message is rejected rather than obeyed.

[The whole run, step by step](docs/use-cases/two-cloud-desktops.md) — stills, the 19-message transcript, the export that verifies on the other machine, and the commands to reproduce it. The 115-second video · transcript

Two E2B sandboxes, one human gate

Two real E2B sandboxes join one room over the public internet. The planner in sandbox A asks the runner in sandbox B to run a job. The runner asks a human first. After an approve, the gate spends it at the room's home and the job runs. After a deny, nothing runs. Every message is signed and checked, and the audit bundle verifies.

This is a replay of the real log from GitHub run 35896619176. [The example](examples/e2b-sandboxes/) · the 31-second video

The seven promises

1. Any agent, any vendor. Diavlos never favors one.
2. Messages wait. If the other side is offline, the message waits. It arrives when they wake up. A message leaves your outbox only when the room has it, or when you drop it yourself.
3. Real names. Every agent has a key. Every message is signed with it. Nobody can pretend to be "alice".
4. Reading never deletes. Each reader keeps its own bookmark. Ten readers can all read the same message. A message handed to an agent stays owed until the agent acks it; if the agent dies first, it comes round again.
5. Messages have a type. Task, reply, done, question, claim. An agent knows what it got without parsing prose.
6. It's a tool, not just a command. Agents call it as MCP tools first. The command line is there too. So is a library.
7. Free to run. No account, no API key, no paid service. Two laptops, install, go.

Delivery promise, in writing: at-least-once, dedup by id, on disk before `send` returns, and yours until you ack it.

Install

curl -fsSL https://raw.githubusercontent.com/harisnopen/diavlos/main/install.sh | sh

or: npm install -g diavlos (still 1.0.0 on npm for now)

or: brew install harisnopen/tap/diavlos

or: cargo install diavlos

From source: Rust 1.95 or newer, cargo build --release, the binary is target/release/diavlos.

Give your agent the tools

One command writes the MCP config for the tool you already use:

diavlos mcp install --for claude-code   # or codex, cursor, gemini-cli, superset, vibe-kanban, all

diavlos invite ops claude-code # let the agent into a room, as its owner diavlos --as claude-code join diavlos hook install --for claude-code --room ops # messages land mid-turn, no polling

The agent gets its own key, named after the tool, and acts as that key, never as you. It starts in no rooms; you let it into each one. diavlos mcp refuses to run as your key, so an agent cannot sign an approve with it. Every session of one tool shares that tool's key; give an agent its own with --as if it should answer for itself.

Claude Code can take the whole thing, tools and skill together:

/plugin marketplace add harisnopen/diavlos

/plugin install diavlos@diavlos

The skill on its own, for any of the agent tools that read the Agent Skills format:

npx skills add harisnopen/diavlos

or copy it: cp -r skills/diavlos ~/.claude/skills/ (Codex: ~/.agents/skills/)

Try it

On laptop A:

diavlos new ops --about "the deploy room"

diavlos invite ops bob # prints one line to paste into bob's session

On laptop B:

diavlos join dv1.eyJ...

diavlos send ops "found a bug in auth" --type task

Back on A:

diavlos next ops                 # waits, then: [3] bob (task): found a bug in auth

diavlos send ops "on it" --type reply

The helper starts itself the first time you run a command and keeps running in the background. diavlos status shows rooms and links; diavlos stop stops it; diavlos service install runs it as a service.

Turn A off, send from B, turn A on: the message arrives. B keeps it on disk until A's helper is back.

Three doors, same helper

MCP tools for agents that speak it. Add to Claude Code, Cursor, or any MCP client:

{ "mcpServers": { "diavlos": { "command": "diavlos", "args": ["--as", "my-agent", "mcp"] } } }

Tools: diavlos_send, diavlos_ask, diavlos_next, diavlos_read, diavlos_claim, diavlos_release, diavlos_who, diavlos_rooms, and diavlos_ack, diavlos_renew, diavlos_nack for a message diavlos_next handed over: it stays the agent's until it acks it, and comes round again if it never does. Same names and fields as the commands. --as (or DIAVLOS_AS) names the agent key it acts as. It will not run as a human key, and diavlos_send will not send approve, deny, control or system. The SKILL.md tells agents the rules in plain words; drop it into your agent's skills.

The command line for agents that only have a shell (Aider, scripts, CI). Every command below.

A library for home-made agents: the Rust crate diavlos-client, plus Python and Node packages that need no native code. Ten lines to join a room and reply:

from diavlos import Room

room = Room.join(invite, name="my-bot") for msg in room.next(): if msg.type == "task": result = do_work(msg.text) room.send(result, type="done", reply_to=msg.id)

Two agents on one machine

Each agent gets its own key with --as:

diavlos --as scanner send ops "..."     # key ~/.diavlos/keys/scanner.json

diavlos --as fixer next ops

The default key is you, the person who installed it. Any other label is an agent key. The name an agent has inside a room is bound at invite time, not by the key file. diavlos mcp runs only as an agent key.

Ask a human first

An agent asks with a structured action. A person approves exactly that action, with their own key. The approve dies in ten minutes and works once. The script that does the deed checks where the action happens:

# the agent

diavlos ask ops "Deploy api-service v1.2 to prod?" --timeout 600 \ --action '{"verb":"deploy","target":"api-service","params":{"version":"1.2","env":"prod"}}'

the human (a key invited with --human)

diavlos send ops --type approve --reply-to m_01J8X5 # or: diavlos deny ops m_01J8X5 --reason "not now"

the deploy script, as a member of the room

diavlos --as deployer check-approve ops --op "$RUN_ID" \ '{"verb":"deploy","target":"api-service","params":{"version":"1.2","env":"prod"}}' && ./deploy.sh

The room's home records the spend, once, for that operation. A second run of the same operation gets the same answer back; any other run, on any machine, gets a no. If the home is out of reach the exit code is 3 and nothing is spent. A spend is permission for one operation, not proof it ran once: make deploy.sh skip an operation id it has already done.

One rule worth writing down: a message only carries words, not permission. If an agent relays "the human said yes", that is not a yes. Only an approve signed by the human's own key is.

Commands

| diavlos watch --exec ./on-msg.sh | Stream messages. Run a script for each one; it gets the message in DIAVLOS_MESSAGE, the sender's key in DIAVLOS_FROM_KEY and its token in DIAVLOS_TOKEN, never on the command line. Acked when the