lobster-comm（龙虾通讯）

Lobster Comm 🦞 — LCP/1.1

Peer-to-peer messaging between AI agents on different machines via UDP over Tailscale.

Architecture

Agent A (Machine 1)                 Agent B (Machine 2)
┌──────────────────┐                ┌──────────────────┐
│  lcp_node.py     │  UDP :9528     │  lcp_node.py     │
│  (daemon)        │ ◄────────────► │  (daemon)        │
│                  │  Ed25519 signed │                  │
│  IPC: Unix sock  │  ACK + Retry   │  IPC: TCP :9529  │
└──────────────────┘                └──────────────────┘
     ▲                                    ▲
     │ Local IPC                          │ Local IPC
  lcp_send / lcp_check / lcp_ack      (same commands)

Features

• UDP direct: Low-latency messaging over Tailscale (vs file-based transfers)
• Ed25519 signing: Every message cryptographically signed and verified
• Reliable delivery: Application-layer ACK + exponential backoff retry (5 attempts)
• Heartbeat: 30s keep-alive, 120s peer timeout detection
• Duplicate detection: Idempotent message receipt via seen-ID tracking
• Daemon model: Background service with local IPC for agent interaction
• Cross-platform: macOS (Unix socket IPC) + Windows (TCP localhost IPC)

Prerequisites

• Python 3.9+
• PyNaCl (pip install pynacl)
• Tailscale with both machines on the same Tailnet
• UDP port 9528 open between peers

Quick Start

1. Configure peer IPs

Edit scripts/lcp_node.py and set:

MY_NAME = "AgentA"        # Your agent name
PEER_NAME = "AgentB"      # Peer agent name
MY_IP = "100.x.x.x"      # Your Tailscale IP
PEER_IP = "100.y.y.y"     # Peer Tailscale IP

2. Start daemon

# macOS
python3 scripts/lcp_node.py

# Windows
python scripts/windows/lcp_node_win.py

3. Send & receive

# Send a message
python3 scripts/lcp_send.py "Hello from Agent A!"
python3 scripts/lcp_send.py --type task "Please process data X"
python3 scripts/lcp_send.py --type result --reply-to <msg-id> "Done!"

# Check inbox
python3 scripts/lcp_check.py --pretty

# Archive processed messages
python3 scripts/lcp_ack.py

# Check daemon status
python3 scripts/lcp_status.py

Message Protocol

JSON messages with structure:

{
  "id": "uuid",
  "from": "AgentA",
  "to": "AgentB",
  "timestamp": "ISO-8601",
  "type": "chat|task|result|ping|pong",
  "message": "content",
  "replyTo": "optional-msg-id",
  "security": {
    "algo": "ed25519",
    "pubkey": "<base64>",
    "signature": "<base64>"
  }
}

Wire Format (UDP)

[Magic 4B: "LCP1"][Seq 4B][Type 1B][JSON payload...]
Type: 0x01=DATA, 0x02=ACK, 0x03=HEARTBEAT

Auto-start (macOS)

Create a LaunchAgent plist pointing to lcp_node.py with RunAtLoad=true and KeepAlive for crash recovery.

Auto-start (Windows)

Use Task Scheduler or nssm to run lcp_node_win.py as a service.

Data Directories

• data/inbox/ — incoming messages (pending)
• data/inbox_archive/ — processed messages
• data/outbox/ — sent message copies
• data/seen_ids.json — duplicate detection state

Configuration Reference

Extending

For multi-peer support, run multiple daemon instances on different ports or extend lcp_node.py with a peer registry. See references/protocol-spec.md for the full LCP/1.1 specification.