VSM-CLI

A decentralized, invisible mesh — directly in your terminal.

VSM-CLI is a high-performance terminal application that acts as an autonomous node in a decentralized mesh. It combines local AI-powered document ingestion, secure peer-to-peer networking (via libp2p), and agentic capabilities (via OpenClaw) to form an intelligent, self-organizing knowledge unit.

Built for speed, security, and anonymity, VSM-CLI allows you to reason over your local data and interact with a global mesh of peers without relying on any central infrastructure.

---

✨ Features

Feature	Description
Terminal TUI	A premium, theme-aware terminal interface with tabbed navigation (Dashboard, Chat, Network) powered by charsm.
Local Ingestion	Watches your local directories. Automatically parses, summarizes, and indexes .md, .txt, and .pdf files.
Flat P2P Mesh	Peer-to-peer communication via libp2p with mDNS discovery and Kademlia DHT. No hierarchy—everyone is a peer.
Agentic Pulsing	Interactive agent chat that can "pulse" local context or remote peers to retrieve knowledge and execute tasks.
Tor Anonymity	Built-in Tor hidden service support for anonymous, NAT-piercing connections across the mesh.
Cryptographic Security	Invite-only mesh membership using Ed25519 signatures. Only authorized peers can exchange data.

---

🚀 Getting Started

1. Installation

Clone the repository and install dependencies:

git clone https://github.com/cezarpena/vsm-cli.git
cd vsm-cli
npm install

2. Global Command (Optional)

To make the vsm command available anywhere on your system:

npm link

3. Configuration

Copy the template and add your API keys (OpenAI-compatible):

cp .env.example .env

Set your OPENAI_API_KEY and any specialized providers like CEREBRAS_API_KEY.

---

🛠 Usage

Start your node using the CLI:

# Basic start
npm start

# Custom configuration
vsm --port 4001 --name "Alpha-Cell" --watch ./my-data --peer-id ./my-identity.json

CLI Flags

Flag	Description
--port	The TCP port for incoming libp2p connections (default: 4001).
--watch	The directory to watch for document ingestion.
--name	Your node's display name in the mesh.
--peer-id	Path to your peer_id.json identity file.

---

🕹 Terminal Navigation

Once the TUI is running, use these keys to navigate:

• [1-3]: Switch between Tabs (Dashboard, Chat, Network).
• [Tab]: Cycle to the next tab.
• [Arrows]: Move selection in lists (Peers).
• [Enter]: Open chat input or join mesh.
• [N]: Change display name.
• [J]: Join a mesh (requires invite code).
• [I]: Generate an invite for the selected peer.
• [L]: Leave mesh and clear authorized state.
• [Ctrl+C]: Graceful shutdown.

---

🧪 Multi-Instance Testing

To test the P2P mesh locally, you can spawn two nodes in separate terminals:

Terminal 1 (Node A):

npm start -- --port 4001 --name "Alpha" --peer-id ./alpha_id.json --watch ./watch_alpha

Terminal 2 (Node B):

npm start -- --port 4002 --name "Beta" --peer-id ./beta_id.json --watch ./watch_beta

Connecting Node A to Node B:

1. In Node A, go to the Network tab (3).
2. Copy your Peer ID (Action [C] on Dashboard or just read from Dashboard).
3. In Node B, select Node A in the "Discovered" list and press [I] to generate an invite for them.
4. Copy the invite code and paste it into Node A using [J].
5. Once authorized, Node A and Node B can pulse each other via the Chat tab.

---

🏗 Architecture

VSM-CLI is built as a stateless-first, peer-to-peer system:

• Networking: Powered by libp2p using TCP, Noise encryption, and Yamux muxing.
• Storage: Uses KuzuDB for graph-based knowledge storage and local file systems for flat metadata.
• Agentic Logic: Integrated with OpenClaw for tool execution and multi-agent reasoning.
• TUI Layer: A custom WASM-backed rendering engine (charsm) providing a fluid terminal experience.

---

🤝 Contributing

Contributions are welcome! Please fork the repository and open a Pull Request.

---

📄 License

Experimental Cybernetic Design. See repository for license details.