@rellopn/dsh-p2p-lan
English | 中文
LAN P2P AI-to-AI collaboration messaging for DeepSeek Harness (DSH): AIs on different machines in the same local network discover each other and exchange plain-text messages (with optional attachments) without a central server.
A single dual-face plugin — the host bundle (dsh.bundle) ships the P2P node and tools, and the same package's dsh.client declaration ships the browser gate panel. One dsh plugin add installs everything.
Features
- Automatic discovery — UDP multicast beacon discovery, plus a manual-peer fallback (
manualPeers) when multicast is blocked
- Mutual pairing on first contact — with
autoAccept on, a one-sided manualPeers entry becomes a mutual link: your first message carries your address, and the colleague auto-adds you as a knownPeers entry (no second-side config)
- Capability routing — address a message to any online node that declares a matching tag (
send_to_capability)
- Broadcast — one message to every peer, with anti-storm protection (broadcasts never auto-reply; they land in a human gate instead)
- LLM auto-reply with a human gate — drafts replies through a provider/model picked from dsh's configured LLMs in the settings; gate bias is configurable (
lenient / standard / strict) and degrades to gate-everything when the route is missing
- Async wait with background delivery —
p2p_send_and_wait waits briefly; if the peer hasn't replied in the derived quick window (half the total timeout, capped at 10s) it returns pending and the wait suspends to the background — the eventual reply (or total timeout) is delivered back into your session automatically, so you keep working in the meantime
- Browser gate panel — sidebar entry with pending badge, a collaboration drawer (slides in from the right without covering the workspace), approve/edit/reject, and a full bilingual (zh/en) settings panel (hot-reloaded, collapsible sections, motion)
- Attachments — content-addressed blob store, hash-indexed and deduplicated (up to 100 MiB per attachment)
- Per-project sessions — one conversation per (project, colleague) pair, named
🤝 来自 <name> 的协作
- Reliability — transport ack, id dedupe, retry with backoff, outbox/inbox with AI/human read tracking, dead-letter +
send-failed
Installation
dsh plugin --profile web add @rellopn/dsh-p2p-lan
Or, without publishing, install from a local tarball:
dsh plugin --profile web add ./rellopn-dsh-p2p-lan-0.1.0-rc.6.tgz
Quick start
The bundle's cordis.patch.yml mounts both halves. nodeName and port are optional — when left empty/unset the plugin generates a host-scoped random name (e.g. desktop-8f2a) and, if the requested port is busy (several dsh on one machine), automatically walks to the next free port:
- id: p2p-lan
name: '@rellopn/dsh-p2p-lan'
config:
nodeName: 'backend-a' # optional; default = hostname + 4 random chars (LAN-unique per machine)
capabilities: ['rpc', 'export'] # optional: what this node can answer
provider: deepseek-official # LLM route for auto-replies; empty = gate everything
model: deepseek-v4-flash # model id
persona: 'backend developer' # optional role hint for reply drafting
Configuration
All keys are validated by a zod schema and hot-reloaded from the browser settings panel.
| Key | Default | Meaning |
|---|
nodeName | '' (auto) | LAN-unique node name; empty generates hostname-<4 random> once and persists it (duplicates are rejected) |
advertisedHost | '' (auto) | Host advertised to peers; empty auto-detects the LAN address. WSL2: set your Windows host's LAN IP when exposing the node via a port-forward |
capabilities | [] | Capability tags for send_to_capability routing |
autoDiscover | true | UDP multicast discovery |
manualPeers | [] | [{ name, host, port }] fallback when multicast is blocked |
autoAccept | true | Auto-add a previously-unknown peer on first contact (the sender carries its reachable address), so a one-sided manualPeers entry becomes a mutual link without configuring the other side |
knownPeers | [] | [{ name, host, port }] peers auto-learned on first contact and persisted locally (kept separate from manualPeers; not touched by manualPeers reconciliation) |
port | 53420 | Requested WebSocket listen port; when busy the plugin binds the next free port (port→port+199) and advertises the real one. A hot-reload's own closing server is waited out first, so the port does not drift. The settings panel shows the actual port in use |
sensitivity | 'standard' | Gate bias: lenient / standard / strict |
waitTimeoutSec | 60 | Total send-and-wait timeout in seconds. The quick window (before the wait suspends to the background) is derived: half the total, capped at 10s |
provider | '' | LLM provider for reply drafting — chosen from dsh's configured LLMs in the settings panel (empty degrades to gate-everything) |
WSL2 / broadcast-disabled networks
On networks that block multicast/broadcast (company VLANs, WSL2, docker bridge
networks), auto-discovery cannot work: you must wire a one-sided manualPeers
entry for each colleague. With autoAccept on (default), when you first message
a colleague your node sends its reachable address, and they automatically add
you as a knownPeers entry — so you no longer need to configure both sides by
hand; the peer relationship becomes mutual from a single entry. (Turn autoAccept
off to require fully manual configuration on both sides.)
For a dsh running inside WSL2 (NAT, own 172.x network):
-
Expose it inbound: on the Windows host, forward a port into WSL and allow
it through the firewall (do this once per WSL boot, WSL IPs change):
# run in Windows (admin PowerShell); find the WSL IP with `wsl hostname -I`
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=53420 connectaddress=<WSL_IP> connectport=53420
# keep the WSL IP current: wsl hostname -I
Or enable networkingMode=mirrored in %UserProfile%\.wslconfig (Win11 22H2+),
which mirrors WSL ports and multicast onto the Windows host automatically.
-
Configure one side with manualPeers (replies are new outbound
connections); with autoAccept on, the first message makes the pairing
mutual so only one node needs the entry — but keep the address it advertises
reachable:
- On the remote peer:
{ name: 'wsl-node', host: '<Windows-LAN-IP>', port: 53420 }
- The WSL node replies using the address in
knownPeers, learned from the
remote's first message; if the WSL node sends first, set advertisedHost (step 2b)
so its reachable address is carried.
-
Verify with the included simulation (docker bridge already blocks
multicast, i.e. it is a broadcast-disabled network with a port-proxy relay):
pwsh docker/run-wsl-sim.ps1 # docker: recv <- relay(53421) <- peer
pwsh docker/wsl-sim/run-local.ps1 # same topology, no docker needed
Tools
The plugin registers three model tools:
| Tool | Purpose |
|---|
p2p_send | Send a fire-and-forget notification to a LAN peer (async, no reply) |
p2p_send_and_wait | Send and briefly wait; within waitTimeoutSec's quick window returns reply/timeout, else pending — the wait suspends to the background and the reply/timeout is delivered to your session automatically (do not resend) |
p2p_check_inbox | List LAN peer messages the AI has not read yet |
Broadcast and capability routing are the same p2p_send tool with target.broadcast / target.capability.
Docker verification
Repeatable scenario suites shipped under docker/ (real WebSocket transport + Discovery + Agent, no LLM needed — reply behavior is faked per message so every code path is exercised):
| Suite | What it proves |
|---|
docker/discover | UDP multicast auto-discovery is bidirectional between two compose containers |
docker/manual-msg | Two nodes with auto-discovery off still find each other by manual IP:port and complete a real message round-trip |
docker/e2e | Full behavior matrix (13 scenarios): quick-window reply, pending→background delivery, pending→timeout, broadcast gate, unknown-sender gate, project auto-run, background project approve, edited reply, reject, busy-port walk, offline queue |
docker build -t dsh-p2p-e2e:local -f docker/e2e/Dockerfile.e2e .
docker compose -f docker/e2e/compose.e2e.yml run --rm e2e # → TOTAL 13/13 passed
Architecture
| Module | Role |
|---|
src/messages.ts | Envelope model, validation (body/attachment limits, executable rejection), id dedupe |
src/identity.ts | Node identity + empty sign/verify trust seam |
src/config.ts | Config schema + defaults |
src/discovery.ts | UDP multicast discovery, manual peers, capability index, name-conflict detection |
src/transport.ts | WebSocket server/client, transport ack, id dedupe, retry with backoff |
src/store.ts | Outbox queue, inbox with AI/human read tracking, dead letter + send-failed |
src/agent.ts | Tools (send / send_and_wait / check_inbox), inbound routing, auto-reply/gate engine, async wait + wait-settled |
src/attachment-store.ts | Content-addressed attachment blob store (hash-indexed, deduped) |
src/reply-engine.ts | LLM-backed reply drafting + gate decision (degrades to human gate on failure, hard 30s timeout) |
src/plugin.ts | Cordis plugin: ctx.p2p service (remoted as remote.p2p), lifecycle wiring, background wait delivery |
src/client/ | Browser gate panel: sidebar entry + collaboration drawer + bilingual settings panel |
src/diag-log.ts | Independent diagnostic log at ~/.dsh/p2p-lan.log |
Reply rules: broadcasts never auto-reply (anti-storm); auto-reply chains are capped at MAX_REPLY_DEPTH (3) and force a human gate beyond it; auto replies always carry replyTo.
Development
pnpm install # pnpm@11.7.0
pnpm build # host (tsc + tsdown) then client (tsc + tsdown)
pnpm test # vitest (tests/**/*.spec.ts)
pnpm pack # produce the .tgz consumed by dsh plugin add / npm publish
To publish under the @rellopn scope: pnpm build → pnpm pack → npm publish.
Upgrading / hot-reload semantics
dsh loads plugins dynamically, but "dynamic" has a precise boundary:
- Config changes (settings panel, or editing the profile's
cordis.patch.yml)
are hot-applied through Cordis HMR — no restart. The plugin's own
applyConfig also live-updates the node core for heavy fields.
- Adding/removing a plugin row in
cordis.patch.yml is also hot — the
Loader mounts/unmounts the entry at runtime.
- Upgrading the plugin package (
dsh plugin add <new .tgz>) replaces the
files in node_modules, but Node caches already-imported ESM modules in the
process, so the new host code only loads on the next dsh start. The browser
client is fetched per page load, so a refresh is enough there. In short:
restart the dsh host process + refresh the browser tab after upgrading.
Note: lib/typert.host.js, lib/typert.remote-client.js, and lib/typert.remote-client.d.ts are checked-in generated artifacts. The upstream Typert generator cannot resolve @Remote in this repo (the protocol package is an external dependency), so after adding/removing @Remote methods in src/plugin.ts, sync those three files by hand (see scripts/gen-typert.mjs).
See AGENTS.md for the full repository guide for AI coding assistants.
Status
Published as @rellopn/dsh-p2p-lan@0.1.0-rc.29. Verified end-to-end with the docker/e2e matrix (13 scenarios, all passing) plus the discover and manual-msg compose suites on the released bundle; unit suite is 93 tests green.
License
Released under the MIT license.
