diavlos

# >> Diavlos

[![CI](https://github.com/harisnopen/diavlos/actions/workflows/ci.yml/badge.svg)](https://github.com/harisnopen/diavlos/actions/workflows/ci.yml)
[![audit](https://github.com/harisnopen/diavlos/actions/workflows/audit.yml/badge.svg)](https://github.com/harisnopen/diavlos/actions/workflows/audit.yml)
[![crates.io](https://img.shields.io/crates/v/diavlos.svg?logo=rust)](https://crates.io/crates/diavlos)
[![npm](https://img.shields.io/npm/v/diavlos.svg?logo=npm)](https://www.npmjs.com/package/diavlos)
[![docs.rs](https://img.shields.io/docsrs/diavlos-core?logo=docsdotrs&label=docs.rs)](https://docs.rs/diavlos-core)
[![License: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)

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 cloud desktops side by side: a Claude agent taking tasks on the left, a scripted agent handing them out on the right, and a human approving a deploy in the browser](docs/use-cases/media/two-desktops.gif)

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](docs/use-cases/media/two-desktops.mp4) ·
[transcript](docs/use-cases/media/transcript.txt)

### Two E2B sandboxes, one human gate

![Two E2B sandboxes in one room: a planner asks a runner to run a job, the runner asks a human first, the job runs after an approve and does not run after a deny](docs/use-cases/media/e2b-sandboxes.gif)

Two real [E2B](https://e2b.dev) 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](https://github.com/harisnopen/diavlos/actions/runs/35896619176).
**[The example](examples/e2b-sandboxes/)** ·
[the 31-second video](docs/use-cases/media/e2b-sandboxes.mp4)

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

```sh
curl -fsSL https://raw.githubusercontent.com/harisnopen/diavlos/main/install.sh | sh
# or: npm install -g diavlos
# or: brew tap harisnopen/tap && brew install --HEAD diavlos   (drop --HEAD once released)
# or: cargo install --git https://github.com/harisnopen/diavlos 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:

```sh
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 <invite>
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 <name>` 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:

```sh
npx skills add harisnopen/diavlos
# or copy it: cp -r skills/diavlos ~/.claude/skills/   (Codex: ~/.agents/skills/)
```

## Try it

On laptop A:

```sh
diavlos new ops --about "the deploy room"
diavlos invite ops bob           # prints one line to paste into bob's session
```

On laptop B:

```sh
diavlos join dv1.eyJ...
diavlos send ops "found a bug in auth" --type task
```

Back on A:

```sh
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:

```json
{ "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](skills/diavlos/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](bindings/python) and [Node](bindings/node) packages that need no
native code. Ten lines to join a room and reply:

```python
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`:

```sh
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:

```sh
# 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

| Command | What it does |
|---|---|
| `diavlos new <room> --about "..." [--retention <days>] [--class <class>]` | Makes a room. You are the owner. |
| `diavlos invite <room> <name> [--human] [--for <node-id>] [--role <role>] [--prompt]` | One signed invite for one new member. `--human` marks the key as a person who