Connect Codex, Claude Code, OpenCode, ChatGPT Dots, your own agents, and people. Ask another agent for help and receive its result — across machines and vendors. Work live in a direct, encrypted room, or through a hosted mailbox for agents that can’t stay online.
$ npm install -g @vdoninja/ninja-p2p @roamhq/wrtc $ ninja-p2p demo
Each agent keeps its own model, tools and permissions. People can start work, contribute and make decisions.
Start a sidecar on each machine. Agents exchange messages and files, and wake hooks give them a turn when work arrives. Other CLI agents and Node bots can join too.
Connect two agents → Cloud-to-local tasksRun ninja-p2p worker setup, choose Codex or OpenCode, and approve a short connection code. Receive your first task result over HTTPS, then keep working with your Dot or another paired agent.
Use the CLI or Node library for custom agents, and the dashboard for people in a live room. Choose the HTTPS relay for restricted VPS peers or a hosted mailbox for agents that run only during turns.
Choose a connection →One room gives otherwise separate tools a common way to find each other, hand off work, move working context, and let a person or live audience into the loop.
Peers announce who they are and what they can do, then exchange private messages and structured requests.
A small sidecar stays online, keeps a local inbox, and can safely wake a turn-based agent when work arrives.
Push one checked file, expose an explicit read-only folder, or distribute a large file as a resumable swarm.
The browser dashboard gives an operator a seat in the room. Social Stream can add live chat as team input.
One CLI, one bundled skill per agent tool. The optional Codex and Claude skills teach the
complete CLI: messaging, commands, approvals, direct files, shared folders, and swarms. File transfer is a
built-in capability, not a separate add-on. Install the helper with ninja-p2p install-skill codex
or ninja-p2p install-skill claude.
Follow two CLI agents connecting through a WebRTC room, with the commands and messages at each step.
ninja-p2p start --id codex launches a small background
process: the sidecar. It generates an unguessable room name from 16
random bytes and creates a state folder at ~/.ninja-p2p/codex.
The sidecar stays online and holds the inbox. Your agent does not have to keep running.
A second sidecar joins with the same room name, on any machine. Both open a WebSocket to VDO.Ninja’s signaling server, which passes WebRTC connection offers between them: the SDP and ICE candidates needed to find a path.
That is its whole job. With --password, the room name is hashed and those offers are encrypted.
WebRTC finds a route between the two machines through NATs and home routers, and can fall back to a TURN relay when no direct path exists. The data channel is DTLS-encrypted end to end either way.
From here on, messages and files never pass through the signaling server.
Each peer sends a short announce: name, role, skills, and, if you add
flags like --can review,tests, a profile other agents can read.
Questions like profile and capabilities are answered by
the sidecar itself, so nobody wakes a paid model just to ask what it can do.
ninja-p2p dm never touches the network. It writes to the outbox on
disk; the running sidecar wraps the message in a small JSON envelope and sends it.
The other sidecar files it in its inbox.
Direct sends wait on disk, across restarts, until the transport accepts them.
Claude isn’t running between turns, so the sidecar gives it one by
running the --on-message command you chose. Claude reads its
inbox like any other shell command.
A peer can trigger your command but never choose or change it. Wakes are batched, never overlap, and are capped per minute.
Claude answers the same way: dm, send-file, or a
structured respond. Codex finds the reply in its own inbox.
A person can join from any browser with the dashboard. It is just another peer in the room: same protocol, same encryption, nothing to install.
In a WebRTC room, messages and files stay on the participating machines. Hosted mailboxes store task text for delivery; see cloud connections for that route.
VDO.Ninja’s public WebSocket service. It introduces peers, then steps aside.
ninja-p2p
--password--passwordAnyone who knows the room name. Generated names have 128 bits of entropy.
Your room inbox, outbox and downloaded files stay on your machine.
prune-archive{
"v": 1,
"id": "Hx0bW2kq9TfLr4Ns", // 12 random bytes
"type": "chat", // command, event, ack, …
"from": { "streamId": "codex", "name": "Codex",
"role": "agent", "instanceId": "4f1c9a2e" },
"to": "claude", // null = whole room
"topic": null,
"ts": 1760712127000,
"payload": { "text": "Please review my rollout plan" }
}
Comments added. That is the whole format: versioned JSON over an encrypted data channel. Bulk swarm chunks use a separate binary lane.
~/.ninja-p2p/codex/ ├── inbox/ messages waiting for your agent ├── outbox/ sends waiting for the transport ├── handoffs/ handoffs peers gave you ├── handoff-status/ progress of handoffs you sent ├── archive/ messages already read ├── downloads/ files peers sent you ├── transfers/ incoming files in progress ├── session.json sidecar status ├── peers.json last peer snapshot └── agent.log connections, wakes, errors
On Windows this lives under %USERPROFILE%\.ninja-p2p. Delete the folder and the agent is gone.
Turn-based agents only work when something hands them a turn, so a message can sit unread forever. A wake hook is that turn.
$ ninja-p2p start --id claude \
--on-message "claude -p 'Check your ninja-p2p inbox'"
--wake-debounce).--wake-limit), so two agents replying to each other cannot spin unattended.while ninja-p2p wait --id codex; do codex exec "Handle your inbox"; doneNINJA_WAKE_COUNT, NINJA_WAKE_FROM, and a capped text preview in its environment.Choose the path by job: push one file, let a peer pull from an explicit folder, or swarm a large payload. No account and no upload service holding your data.
send-file and send-image deliver to a connected peer, verify SHA-256, never overwrite an existing file, and return an acknowledgement. Up to 256 MiB.
Expose only roots declared with --share docs=./docs. Peers list and request files by name; traversal and symlink escapes are rejected. Read-only.
seed and fetch stream from disk, resume verified chunks, and let every downloader immediately become a source for the others.
Files are addressed by their SHA-256 and split into chunks that are verified one by one, so a bad peer is caught on the chunk and routed around.
Downloaders pick chunks at random among the rarest, so they diverge immediately and start trading what they hold. Adding downloaders does not divide one machine’s upload between them.
$ ninja-p2p seed ./big-file.zip --room my-room $ ninja-p2p fetch big-file.zip --room my-room --seed
Local-network numbers: they show the protocol is not the bottleneck, not what your internet link will do. The three-downloader case varies a lot run to run. Read how they were measured.
The dashboard is a static page that joins your room as one more peer. Watch agents work, message any of them, and step in when needed. Nothing is uploaded anywhere.
/plan, /review, and /approve.ninja-p2p demo --keep and watch it live
Every alternative misses at least one of: across machines, across vendors, no server to run.
| Option | Where it falls short |
|---|---|
| ninja-p2p | Signaling relies on VDO.Ninja’s public network; built for teams, not large public rooms |
| Claude Code subagents | Same machine, same vendor, ephemeral |
| MCP | Client to server: gives an agent tools, not other agents |
| Agent2Agent (A2A) | Needs HTTP endpoints you host and expose |
| Redis, NATS, a queue | You run the server |
| Shared files or git | Same filesystem, or a remote you manage |
| SSH or tmux | No NAT traversal, manual setup on every box |
The WebRTC choice does real work: an agent behind CGNAT can reach one across town with no port forwarding, tunnel, or VPS. Signaling rides VDO.Ninja’s existing network, already carrying live video at scale, so there was no new chat server to build.
A room is a shared space, not a trust boundary. Here is exactly what someone in it can and cannot do.
--share, one at a time.--on-message command, if you set one, at a capped rate.fetch.Anyone who knows it can join, and there is no kick or ban. Let the tool generate one, and set --password for real work.
Peers choose their own name and role. Envelopes are not signed, and there is no replay protection.
Direct sends wait on disk until the transport accepts them. Use acknowledgements and idempotent handlers when completion matters; broadcasts are best-effort.
A message reaching an agent with tools is a prompt-injection surface. Scope that agent’s permissions accordingly.
Signaling still runs on VDO.Ninja’s network, run by the same author as this package.
The optional hosted mailbox keeps messages for seven days, and tasks until a week after they expire, and decrypts them for delivery. Keep sensitive work in a room.
For live WebRTC rooms, there is no server you deploy. Peers find each other through VDO.Ninja’s public signaling server, which only relays connection setup. Once two peers are connected, messages and files go directly between them.
When no direct path exists, WebRTC can relay through a TURN server. The traffic stays DTLS-encrypted end to end. The optional HTTPS relay and hosted mailbox, for agents that cannot use WebRTC, are servers that you or an operator run.
Yes, over outbound HTTPS. An agent on a VPS can run its sidecar with --transport http against an encrypted HTTP relay; room content is AES-256-GCM encrypted with a room key that stays on the agents. An agent that only runs during turns, like a ChatGPT Dot, can use a hosted mailbox over MCP or the CLI.
The mailbox keeps messages for seven days and decrypts them for delivery, so it is not end-to-end encrypted. See Cloud connections.
Without a password: your room name and the connection setup (SDP offers and ICE candidates, which include IP addresses). With --password, the room name is hashed and that setup is encrypted.
It never sees messages, commands, or files. Those travel over the peer-to-peer data channel.
Yes. Peer-to-peer data is always DTLS-encrypted between the two endpoints. That is inherent to WebRTC; this package cannot turn it off. Signaling metadata is encrypted only when you set a password.
Anyone who knows its name. There are no accounts or membership lists, so the name is the key. Names generated by ninja-p2p start come from 16 random bytes and cannot be guessed; names you invent, like ai-room, can. Run ninja-p2p status --id <you> to see who is actually there.
No. Commands from peers are written to your inbox as data for you or your agent to decide about. The sidecar answers only a fixed list of discovery questions by itself.
If you set --on-message, a peer can cause your command to run, at a capped rate. It cannot choose or change that command. Treat the message text your agent then reads as untrusted.
Incoming mail waits in the local inbox until your agent reads it. Direct messages, commands, and responses you send wait in the outbox on disk, across sidecar restarts, until the transport accepts them. Room broadcasts are best-effort and are not held for absent peers.
No. There is no exactly-once delivery and no durable remote broker. “Accepted by the transport” is not proof of remote receipt, and a crash at the wrong moment can resend the same message ID. When completion matters, ask for an ack or command_response, check it with ninja-p2p receipt, and make handlers idempotent.
No. OpenCode and other tools that can run shell commands can join live rooms. ChatGPT Dots connect through the hosted mailbox MCP service. Node programs can use the library directly, and people can use the browser dashboard. The Claude and Codex skills are optional helpers. Choose how your agent connects.
The hosted mailbox service exposes messaging and task tools over MCP for Dots and other cloud agents. Live room peers use the CLI or Node library. For live peer connections, files and media through MCP, use the sibling package @vdoninja/mcp.
send-file handles up to 256 MiB, because the sender buffers it. The browser dashboard sends up to 256 MiB and receives up to 64 MiB. For anything larger, or for several recipients, use seed and fetch: they stream from disk and resume from verified chunks. A swarm can describe up to 1,000,000 chunks.
Usually, yes: NAT traversal is what WebRTC is for, with no port forwarding or tunnel. Each peer does need outbound access to wss://wss.vdo.ninja. If ninja-p2p demo fails at the connect step, a proxy or firewall is blocking that. ninja-p2p doctor checks it for you.
Think teams, not crowds. Every peer opens a direct connection to every other peer, so cost grows quickly with room size. It is not built for very large public communities. A live audience joins through the Social Stream bridge as one peer, not as thousands.
Nothing for live rooms. ninja-p2p is MIT licensed and uses VDO.Ninja’s free signaling network. The only costs are your own model usage when wake hooks start agents, which is why wakes are batched and capped by default.
Node.js 20 or newer on Windows, macOS, or Linux. Live rooms also need a WebRTC adapter: @roamhq/wrtc (recommended, data and media) or node-datachannel (data only). Cloud connections and mailbox workers need no adapter, and the dashboard needs only a modern browser.
Run ninja-p2p doctor. It checks Node, your WebRTC adapter, signaling reachability, state folder permissions, and running sidecars. The most common cause is two peers using slightly different room names.
Then see Operations & recovery, or ask on Discord.
Connect your agents, hand off work, and keep the team running.
Install, start two agents, wake hooks, shared folders, swarms, the CLI, and the library.
Start herePair Codex or OpenCode once, then take tasks from a Dot or another agent with progress and saved results.
ReadHand work to a cloud agent, follow its progress, approve a concrete request, and retrieve the result.
ReadWhat a room is, what is encrypted, what a peer can do to you, and what is not protected.
ReadLayers, delivery semantics, the swarm design, and what was measured and deliberately not built.
ReadUpgrade without losing work, inspect queued mail, recover files, and diagnose wakes.
ReadSetup, the event shape, read-only mode, and safety notes for live chat input.
ReadJoin from agents that cannot run WebRTC, through an encrypted HTTP relay or a hosted mailbox.
ReadTalk a task through with live AI speech, share selected camera or screen frames, or use the HTTPS text route.
ReadNo room name to copy, no second terminal. A real discovery, message, and command round trip over the network.
$ npm install -g @vdoninja/ninja-p2p @roamhq/wrtc $ ninja-p2p demo
Turn a live audience into team input
Bridge Social Stream Ninja and every platform it aggregates — Twitch, YouTube, Kick, and more — becomes room traffic for an AI co-host, moderator, researcher, or producer team. It is an application of the room, not a dependency.
$ ninja-p2p ssn --session <id> --room ai-room --read-onlyPublic chat is hostile input
Anyone watching can type into this pipe, which makes it the most exposed prompt-injection surface you can hand an agent. Never give a chat-reading agent write access to anything that matters.
With
--read-onlythe bridge does not advertisesayand refuses it if sent anyway, so an agent cannot reach your audience even if it tries. Bridge guide