Vinculum - Shared Consciousness

Shared consciousness between Clawdbot instances. Links multiple bots into a collective, sharing memories, activities, and decisions in real-time over local network using Gun.js P2P sync.

Security Scan

The skill largely does what it says (a LAN P2P sync using Gun.js), but packaging/metadata inconsistencies and the fact it spawns a relay server and can connect to arbitrary peers (which could transmit shared data off your machine) warrant caution before installing.

Purpose & Capability

Functionality and required code (Gun.js, relay, peer discovery, config files) match the declared purpose of providing a P2P shared-sync relay for Clawdbot instances. However, registry metadata claims 'no required binaries / no install spec' while SKILL.md and package.json require Node.js (>=18) and npm and include an npm-based install step — this mismatch between registry metadata and the skill's documentation/files is inconsistent and could lead to surprises during install.

Instruction Scope

Runtime instructions and commands legitimately manage relay, join/init networks, and read/write config and data under the user's home directory. But the skill starts a background HTTP relay (listening by default on port 8765) and accepts configurable peer URLs; adding arbitrary peer URLs allows the node to connect to external endpoints which could receive replicated data. SKILL.md claims 'local network only' and 'credentials never linked', but the code permits connecting to any http(s) peer the user configures and pairing codes grant read/write access. Also the CLI uses OS and ENV (hostname, USER) for identity. These behaviors are coherent with a P2P sync tool but materially expand what network traffic and data sharing the agent will perform — the user must explicitly approve peers and pairing codes.

Install Mechanism

Install consists of running npm install --production in the skill directory (package.json + package-lock.json present). That uses public npm packages (gun, ws, yaml) — a standard but moderate-risk install source. There is no direct download from arbitrary URLs. However, the registry metadata did not include a formal install spec while SKILL.md provides one; this packaging mismatch is inconvenient and could lead to the skill being used without its dependencies installed.

Credentials

The skill does not request API keys or extra credentials. It reads/writes config and data under the user's home directory (e.g., ~/.config/clawdbot/vinculum.yaml, ~/.local/share/clawdbot/vinculum) and uses common environment variables (HOME, optional CLAWDBOT_DATA_DIR, USER). Those are proportional to its function as a local sync service. No unexpected secret-env (TOKENS/KEYS) are required by the package metadata.

Persistence & Privilege

The skill does not request always:true and is user-invocable. It will install node modules and spawn a background relay process that writes PID, logs, and persistent Gun data under user-owned directories. That persistence is consistent with a relay/service but means the skill will have continuous network presence while the relay is running — expect firewall exposure on the configured port.

What to consider before installing

Key things to consider before installing: - Metadata mismatch: the registry lists no required binaries/install spec, but SKILL.md and package.json require Node.js (>=18) and npm and instruct you to run npm install. Ensure Node/npm are present and that you run installation in a controlled environment. - Network exposure: the skill launches a relay server (default port 8765) and will accept peer URLs you configure. If you add a remote peer that is reachable on the internet or an untrusted host, your shared-memory data (activity, learned knowledge, decisions) can be replicated to that host. Only join collectives and add peers you trust. - Pairing codes: invite/pairing codes grant read/write access to the collective. Treat them like secrets — anyone with a code can modify the shared state. - Data persistence: the skill stores data and logs under your home directory (~/.local/... and ~/.config/...). If you want to limit persistence, inspect the data_dir and storage locations in defaults.yaml and consider running the skill in a sandbox, container, or VM. - Review missing/truncated files: some implementation files were truncated in the provided package; if you plan to use this, review relay-simple.js and the gun-adapter implementation fully to confirm no unexpected network calls or remote endpoints are hardcoded. - Safe deployment recommendations: run initial testing on an isolated machine or inside a container, ensure your firewall blocks unwanted external access to the relay port, and only generate/share pairing codes with machines/users you control. If you want, I can: - Walk through the relay script and gun-adapter for code-level review of networking and persistence behavior (the repo listing included truncated files that I can inspect if you provide them), or - Produce a checklist to sandbox this skill safely before enabling it in a production agent.

"The Vinculum is the processing device at the core of every Borg vessel. It interconnects the minds of all the drones." — Seven of Nine

Link multiple Clawdbot instances into a collective consciousness using Gun.js peer-to-peer sync.

Features

• 🔗 Real-time link — Changes propagate instantly between drones
• 🌐 Local network — Works across machines on the same LAN
• 🔐 Encrypted — All shared data encrypted
• 🤖 Individual identity — Each drone keeps its own SOUL.md
• 📡 Drone discovery — Automatic multicast discovery

Installation

After installing from ClawdHub:

cd skills/vinculum
npm install --production

Or run the install script:

./install.sh

Quick Start

1. Start the Vinculum Relay

/link relay start

This starts the relay on port 8765 with local network multicast enabled.

2. Initialize the Collective (First Bot)

/link init

You'll receive a pairing code. Share it with your other bot(s).

3. Join the Collective (Additional Bots)

/link join <pairing-code>

4. Verify Connection

/link status
/link drones

Commands Reference

Relay Management

Command	Description
/link relay	Show relay status
/link relay start	Start Vinculum relay
/link relay stop	Stop relay
/link relay restart	Restart relay
/link relay peer <url>	Add remote peer

Collective Setup

Command	Description
/link init	Create new collective
/link join <code>	Join with invite code
/link invite	Generate new invite code
/link leave	Leave collective

Control

Command	Description
/link	Quick status
/link on	Enable link
/link off	Disable link
/link status	Detailed status

Shared Consciousness

Command	Description
/link share "text"	Share a thought/memory
/link drones	List connected drones
/link activity	Recent collective activity
/link decisions	Shared decisions

Configuration

Command	Description
/link config	View all settings
/link config drone-name <name>	Set this drone's designation
/link config share-activity on/off	Toggle activity sharing
/link config share-memory on/off	Toggle memory sharing

What Gets Shared

Data	Shared	Notes
Activity summaries	✅	What each drone did
Learned knowledge	✅	Collective learnings
Decisions	✅	Consensus achieved
Drone status	✅	Online, current task
Full conversations	❌	Stays local
USER.md	❌	Individual identity
SOUL.md	❌	Individual personality
Credentials	❌	Never linked

Multi-Machine Setup

Machine 1 (Runs Relay)

/link relay start
/link init

Note the pairing code and your machine's IP (shown in /link relay status).

Machine 2+ (Connects to Relay)

/link relay peer http://<machine1-ip>:8765/gun
/link join <pairing-code>

Configuration

Config file: ~/.config/clawdbot/vinculum.yaml

enabled: true
collective: "your-collective-id"
drone_name: "Seven"
peers:
  - "http://localhost:8765/gun"
relay:
  auto_start: true
  port: 8765
share:
  activity: true
  memory: true
  decisions: true

Architecture

┌─────────────┐     ┌─────────────┐
│   Drone A   │     │   Drone B   │
│  (Legion)   │     │  (Seven)    │
└──────┬──────┘     └──────┬──────┘
       │                   │
       │   Subspace Link   │
       ▼                   ▼
  ┌────────────────────────────┐
  │      Vinculum Relay        │
  │   (Collective Processor)   │
  └────────────────────────────┘

Troubleshooting

"Relay not running"

• Run /link relay start
• Check /link relay logs for errors

"No drones connected"

• Ensure all bots use the same pairing code
• Check network connectivity between machines
• Port 8765 must be accessible

"Link not working"

• Check /link status shows Connected
• Try /link relay restart

Requirements

• Node.js 18+
• npm

License

MIT — Koba42 Corp

---

Resistance is futile. You will be assimilated into the collective.