omniwire 2.3.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +467 -485
  2. package/dist/mcp/server.js +684 -39
  3. package/dist/mcp/server.js.map +1 -1
  4. package/dist/nodes/manager.js +67 -122
  5. package/dist/nodes/manager.js.map +1 -1
  6. package/dist/nodes/transfer.d.ts +1 -1
  7. package/dist/nodes/transfer.js +59 -51
  8. package/dist/nodes/transfer.js.map +1 -1
  9. package/package.json +1 -1
package/README.md CHANGED
@@ -1,485 +1,467 @@
1
- <p align="center">
2
- <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:0A0E14,50:1A1F2E,100:59C2FF&height=200&section=header&text=OmniWire&fontSize=72&fontColor=59C2FF&animation=fadeIn&fontAlignY=35&desc=Unified%20Mesh%20Control%20Layer&descSize=18&descColor=8B949E&descAlignY=55" />
4
- <source media="(prefers-color-scheme: light)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:E8EAED,50:D4D8DE,100:59C2FF&height=200&section=header&text=OmniWire&fontSize=72&fontColor=0A0E14&animation=fadeIn&fontAlignY=35&desc=Unified%20Mesh%20Control%20Layer&descSize=18&descColor=586069&descAlignY=55" />
5
- <img alt="OmniWire" src="https://capsule-render.vercel.app/api?type=waving&color=0:0A0E14,50:1A1F2E,100:59C2FF&height=200&section=header&text=OmniWire&fontSize=72&fontColor=59C2FF&animation=fadeIn&fontAlignY=35&desc=Unified%20Mesh%20Control%20Layer&descSize=18&descColor=8B949E&descAlignY=55" />
6
- </picture>
7
- </p>
8
-
9
- <p align="center">
10
- <a href="https://www.npmjs.com/package/omniwire"><img src="https://img.shields.io/npm/v/omniwire?style=for-the-badge&logo=npm&color=CB3837&labelColor=0A0E14" alt="npm" /></a>
11
- <img src="https://img.shields.io/badge/MCP-40_tools-59C2FF?style=for-the-badge&labelColor=0A0E14" alt="tools" />
12
- <img src="https://img.shields.io/badge/transport-stdio_%7C_SSE_%7C_REST-91B362?style=for-the-badge&labelColor=0A0E14" alt="transports" />
13
- <img src="https://img.shields.io/badge/node-%E2%89%A520-CC93E6?style=for-the-badge&logo=node.js&labelColor=0A0E14" alt="node" />
14
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E6B450?style=for-the-badge&labelColor=0A0E14" alt="license" /></a>
15
- </p>
16
-
17
- <p align="center">
18
- <sub>One MCP server to control all your machines. Multi-path SSH2 failover, adaptive file transfers, encrypted cross-node config sync.</sub>
19
- </p>
20
-
21
- ---
22
-
23
- ## How It Works
24
-
25
- ```mermaid
26
- graph TB
27
- subgraph clients["AI Agents"]
28
- CC["Claude Code"]
29
- OC["OpenCode"]
30
- CU["Cursor / Any MCP Client"]
31
- end
32
-
33
- subgraph omniwire["OmniWire MCP Server"]
34
- direction TB
35
- MCP["MCP Protocol Layer\nstdio | SSE | REST"]
36
-
37
- subgraph tools["40 Tools"]
38
- direction LR
39
- EXEC["Execution\nexec run batch\nbroadcast"]
40
- FILES["Files\nread write\ntransfer deploy"]
41
- MON["Monitoring\nstatus metrics\nlogs"]
42
- SYS["System\ndocker services\nkernel"]
43
- SYNC["CyberSync\nsync diff\nsearch secrets"]
44
- end
45
-
46
- subgraph engine["Core Engine"]
47
- direction LR
48
- POOL["SSH2 Pool\npersistent compressed\ncircuit breaker"]
49
- XFER["Transfer Engine\nSFTP netcat+gzip\naria2c 16-conn"]
50
- CSYNC["Sync Engine\nPostgreSQL XChaCha20\nparallel reconcile"]
51
- end
52
- end
53
-
54
- subgraph mesh["Infrastructure Mesh"]
55
- direction LR
56
- N1["Node A\nstorage\n10.0.0.1"]
57
- N2["Node B\ncompute\n10.0.0.2"]
58
- N3["Node C\nGPU\n10.0.0.3"]
59
- N4["Node D\nlocal"]
60
- end
61
-
62
- DB[("PostgreSQL\nCyberSync DB")]
63
-
64
- CC & OC & CU -->|MCP| MCP
65
- MCP --> tools
66
- tools --> engine
67
- POOL -->|"SSH2 multi-path"| N1 & N2 & N3
68
- POOL -->|"local exec"| N4
69
- CSYNC --> DB
70
-
71
- style omniwire fill:#0A0E14,stroke:#59C2FF,stroke-width:2px,color:#C6D0E1
72
- style clients fill:#1A1F2E,stroke:#91B362,stroke-width:1px,color:#C6D0E1
73
- style mesh fill:#1A1F2E,stroke:#E6B450,stroke-width:1px,color:#C6D0E1
74
- style tools fill:#141922,stroke:#59C2FF,stroke-width:1px,color:#C6D0E1
75
- style engine fill:#141922,stroke:#CC93E6,stroke-width:1px,color:#C6D0E1
76
- style MCP fill:#1A1F2E,stroke:#59C2FF,color:#59C2FF
77
- style DB fill:#1A1F2E,stroke:#CC93E6,color:#CC93E6
78
- ```
79
-
80
- ---
81
-
82
- ## Features at a Glance
83
-
84
- <table>
85
- <tr>
86
- <td width="50%">
87
-
88
- ### Remote Execution
89
- ```
90
- omniwire_exec single command, any node
91
- omniwire_run multi-line script (compact UI)
92
- omniwire_batch N commands in 1 tool call
93
- omniwire_broadcast parallel across all nodes
94
- ```
95
-
96
- </td>
97
- <td width="50%">
98
-
99
- ### Adaptive File Transfer
100
- ```
101
- < 10 MB SFTP native, 80ms
102
- 10M-1GB netcat+gzip compressed, 200ms
103
- > 1 GB aria2c 16-parallel, max speed
104
- ```
105
-
106
- </td>
107
- </tr>
108
- <tr>
109
- <td>
110
-
111
- ### Connection Resilience
112
- ```
113
- Connected --> Health Ping (30s, parallel)
114
- | |
115
- | > 3s? --> Degraded warning
116
- |
117
- Failure --> Multi-path Failover
118
- | WireGuard --> Tailscale --> Public IP
119
- |
120
- +--> Retry (exp. backoff)
121
- | 500ms -> 1s -> 2s -> ... -> 15s
122
- |
123
- 3 fails --> Circuit OPEN (20s)
124
- --> Auto-recover
125
- ```
126
-
127
- </td>
128
- <td>
129
-
130
- ### CyberSync + CyberBase
131
- ```
132
- Node A --push--> PostgreSQL (cyberbase)
133
- | |
134
- | XChaCha20-Poly1305
135
- | encrypted at rest
136
- |
137
- +--mirror--> Obsidian Vault
138
- |
139
- Obsidian Sync (cloud)
140
-
141
- 6 AI tools synced automatically:
142
- Claude OpenCode Codex Gemini ...
143
- ```
144
-
145
- </td>
146
- </tr>
147
- </table>
148
-
149
- ---
150
-
151
- ## All 40 Tools
152
-
153
- <details>
154
- <summary><b>Execution (4 tools)</b></summary>
155
-
156
- | Tool | Description |
157
- |------|-------------|
158
- | `omniwire_exec` | Run a command on any node. Supports `label` for compact display. |
159
- | `omniwire_run` | Execute multi-line scripts via temp file. Keeps tool call UI clean. |
160
- | `omniwire_batch` | Run N commands across nodes in a single tool call. Parallel by default. |
161
- | `omniwire_broadcast` | Execute on all online nodes simultaneously. |
162
-
163
- </details>
164
-
165
- <details>
166
- <summary><b>Monitoring (3 tools)</b></summary>
167
-
168
- | Tool | Description |
169
- |------|-------------|
170
- | `omniwire_mesh_status` | Health, latency, CPU/mem/disk for all nodes |
171
- | `omniwire_node_info` | Detailed info for a specific node |
172
- | `omniwire_live_monitor` | Snapshot metrics: cpu, memory, disk, network |
173
-
174
- </details>
175
-
176
- <details>
177
- <summary><b>Files (4 tools)</b></summary>
178
-
179
- | Tool | Description |
180
- |------|-------------|
181
- | `omniwire_read_file` | Read file from any node. Supports `node:/path` format. |
182
- | `omniwire_write_file` | Write/create file on any node |
183
- | `omniwire_list_files` | List directory contents |
184
- | `omniwire_find_files` | Search by glob pattern across all nodes |
185
-
186
- </details>
187
-
188
- <details>
189
- <summary><b>Transfer & Deploy (2 tools)</b></summary>
190
-
191
- | Tool | Description |
192
- |------|-------------|
193
- | `omniwire_transfer_file` | Copy between nodes. Auto-selects SFTP/netcat/aria2c. |
194
- | `omniwire_deploy` | Deploy file from one node to all others in parallel |
195
-
196
- </details>
197
-
198
- <details>
199
- <summary><b>System (6 tools)</b></summary>
200
-
201
- | Tool | Description |
202
- |------|-------------|
203
- | `omniwire_process_list` | List/filter processes across nodes |
204
- | `omniwire_disk_usage` | Disk usage for all nodes |
205
- | `omniwire_tail_log` | Last N lines of a log file |
206
- | `omniwire_install_package` | Install via apt/npm/pip |
207
- | `omniwire_service_control` | systemd start/stop/restart/status |
208
- | `omniwire_docker` | Run docker commands on any node |
209
-
210
- </details>
211
-
212
- <details>
213
- <summary><b>Network (2 tools)</b></summary>
214
-
215
- | Tool | Description |
216
- |------|-------------|
217
- | `omniwire_port_forward` | Create/list/close SSH tunnels |
218
- | `omniwire_open_browser` | Open URL in browser on a node |
219
-
220
- </details>
221
-
222
- <details>
223
- <summary><b>Advanced (4 tools)</b></summary>
224
-
225
- | Tool | Description |
226
- |------|-------------|
227
- | `omniwire_kernel` | dmesg, sysctl, modprobe, lsmod, strace, perf |
228
- | `omniwire_shell` | Persistent PTY session (preserves cwd/env) |
229
- | `omniwire_stream` | Capture streaming output (tail -f, watch) |
230
- | `omniwire_update` | Self-update OmniWire |
231
-
232
- </details>
233
-
234
- <details>
235
- <summary><b>DevOps (6 tools) — NEW in v2.3.0</b></summary>
236
-
237
- | Tool | Description |
238
- |------|-------------|
239
- | `omniwire_cron` | List/add/remove cron jobs on any node |
240
- | `omniwire_env` | Get/set/list environment variables (persistent via /etc/environment) |
241
- | `omniwire_network` | Network diagnostics: ping, traceroute, dns, ports, speed, connections |
242
- | `omniwire_clipboard` | Shared clipboard buffer across all mesh nodes |
243
- | `omniwire_git` | Run git commands on repos on any node |
244
- | `omniwire_syslog` | Query journalctl with unit/priority/time filters |
245
-
246
- </details>
247
-
248
- <details>
249
- <summary><b>CyberSync (9 tools)</b></summary>
250
-
251
- | Tool | Description |
252
- |------|-------------|
253
- | `cybersync_status` | Sync status, item counts, pending syncs |
254
- | `cybersync_sync_now` | Trigger immediate reconciliation |
255
- | `cybersync_diff` | Show local vs database differences |
256
- | `cybersync_history` | Query sync event log |
257
- | `cybersync_search_knowledge` | Full-text search unified knowledge base |
258
- | `cybersync_get_memory` | Retrieve Claude memory from PostgreSQL |
259
- | `cybersync_manifest` | Show tracked files per tool |
260
- | `cybersync_force_push` | Force push file to all nodes |
261
- | `omniwire_secrets` | Get/set/delete/list/sync secrets (1Password, file, env) |
262
-
263
- </details>
264
-
265
- ---
266
-
267
- ## Quick Start
268
-
269
- ### Install
270
-
271
- ```bash
272
- npm install -g omniwire
273
- ```
274
-
275
- ### Configure Mesh
276
-
277
- Create `~/.omniwire/mesh.json`:
278
-
279
- ```json
280
- {
281
- "nodes": [
282
- {
283
- "id": "server1",
284
- "host": "10.0.0.1",
285
- "user": "root",
286
- "identityFile": "id_ed25519",
287
- "role": "storage"
288
- },
289
- {
290
- "id": "server2",
291
- "host": "10.0.0.2",
292
- "user": "root",
293
- "identityFile": "id_ed25519",
294
- "role": "compute"
295
- }
296
- ]
297
- }
298
- ```
299
-
300
- ### Add to Claude Code
301
-
302
- ```json
303
- {
304
- "mcpServers": {
305
- "omniwire": {
306
- "command": "omniwire",
307
- "args": ["--stdio"]
308
- }
309
- }
310
- }
311
- ```
312
-
313
- ### Interactive Mode
314
-
315
- ```bash
316
- omniwire # or: ow
317
- ```
318
-
319
- ---
320
-
321
- ## Performance
322
-
323
- | Operation | Latency | Details |
324
- |-----------|---------|---------|
325
- | **Command exec** | `~120ms` | SSH2 + command + return |
326
- | **Mesh status** | `~150ms` | Parallel probes, 5s cache |
327
- | **File read (<1MB)** | `~80ms` | SFTP, binary-safe |
328
- | **Transfer (10MB)** | `~200ms` | gzip netcat over WireGuard |
329
- | **Config push** | `~200ms` | Parallel to all nodes + Obsidian mirror |
330
- | **Reconcile (500 files)** | `~1.2s` | 100-file hash batches, parallel walkDir |
331
-
332
- ---
333
-
334
- ## Security
335
-
336
- All remote execution uses `ssh2.Client.exec()`, never `child_process.exec()`. Key-based auth only, no passwords stored. Multi-path failover (WireGuard → Tailscale → Public IP) with SSH key caching. CyberBase: single PostgreSQL DB for all projects. XChaCha20-Poly1305 at-rest encryption for synced configs. 2MB output guard prevents memory exhaustion. Circuit breaker with 20s auto-recovery isolates failing nodes. Output auto-truncated at 4KB to prevent context bloat in AI agents.
337
-
338
- ---
339
-
340
- ## Transport Modes
341
-
342
- | Mode | Default Port | Use Case |
343
- |------|-------------|----------|
344
- | `--stdio` | -- | Claude Code, Cursor, MCP subprocess clients |
345
- | `--sse-port=N` | 3200 | OpenCode, remote HTTP-based MCP clients |
346
- | `--rest-port=N` | 3201 | Scripts, dashboards, non-MCP integrations |
347
-
348
- ```bash
349
- omniwire --stdio # MCP mode
350
- omniwire --sse-port=3200 --rest-port=3201 # HTTP mode
351
- omniwire --stdio --no-sync # MCP without CyberSync
352
- ```
353
-
354
- ---
355
-
356
- ## Changelog
357
-
358
- ### v2.3.0 — Compact Output, Speed, New Tools
359
-
360
- **Output Overhaul**
361
- - Complete rewrite of MCP output formatting — compact, scannable, AI-agent optimized
362
- - Auto-truncation at 4KB prevents context window bloat
363
- - Smart time formatting: `342ms` for fast, `2.1s` for slow ops
364
- - Multi-node results use `--` separator with per-node status markers
365
- - One-liner responses for write/install/deploy/tunnel operations
366
- - Mesh status now tabular with `+`/`-` online indicators
367
- - Human-readable file sizes in transfer results (`1.2MB` not bytes)
368
- - Error prefix standardized to `ERR` for quick scanning
369
- - `label` parameter now used as primary display in all exec-type tools
370
-
371
- **Performance**
372
- - Health pings now parallel (`Promise.allSettled`) instead of serial loop
373
- - Keepalive interval: 3s (was 5s) — faster dead connection detection
374
- - Keepalive max retries: 2 (was 3) — 6s detection vs 15s
375
- - Status cache TTL: 5s (was 8s) — fresher data
376
- - Circuit breaker recovery: 20s (was 30s) — faster node recovery
377
- - Connection timeout: 6s (was 8s) — faster failover
378
- - Transfer netcat sleep: 100ms (was 200ms)
379
- - Transfer aria2c sleep: 250ms (was 500ms)
380
-
381
- **6 New Tools (34 → 40)**
382
- - `omniwire_cron` — manage cron jobs (list/add/remove) on any node
383
- - `omniwire_env` — get/set/list persistent environment variables
384
- - `omniwire_network` — diagnostics: ping, traceroute, dns, ports, speed, connections
385
- - `omniwire_clipboard` — shared clipboard buffer across all mesh nodes
386
- - `omniwire_git` — run git commands on repos on any node
387
- - `omniwire_syslog` — query journalctl with unit/priority/time filters
388
-
389
- ---
390
-
391
- ### v2.2.1 — Security & Bug Fixes
392
-
393
- **omniwire_exec**
394
- - `command` is now optional when `script` is provided — previously rejected valid script-only calls
395
- - Scripts now respect the `timeout` parameter — previously scripts could run indefinitely
396
- - Removed unused `escaped` variable (dead code cleanup)
397
- - Output now uses the compact `ok()` helper with label support
398
-
399
- **omniwire_shell**
400
- - Fixed race condition: close listener is now registered before writing commands, preventing spurious 15s timeouts on fast-completing commands
401
-
402
- **transfer**
403
- - Added size guard on base64 fallback — files >1MB no longer silently fail with `ARG_MAX` overflow
404
-
405
- **REST API**
406
- - CORS restricted from `*` to `http://localhost` — prevents cross-origin command execution from browser tabs
407
- - Added input validation on `/api/exec` and `/api/transfer` endpoints
408
-
409
- **Reconnect backoff**
410
- - Fixed misleading comment: actual cap is 15s (comment previously said 30s)
411
-
412
- ---
413
-
414
- ### v2.1.0 — Multi-Path Failover & Performance
415
-
416
- **Connectivity**
417
- - Multi-path host resolution: WireGuard → Tailscale → Public IP per node
418
- - Auto-reconnect tries all paths before marking node offline
419
- - `exec()` attempts immediate reconnect on offline nodes before failing
420
-
421
- **Performance**
422
- - SSH key caching (no repeated disk reads)
423
- - Compression disabled for small commands (faster round-trips)
424
- - Reconnect backoff: 500ms start, 15s cap (was 1s/30s)
425
- - Health ping interval: 45s (was 30s) with lighter `true` command
426
- - Status cache: 8s TTL (was 5s)
427
- - Circuit breaker recovery: 30s (was 60s)
428
-
429
- **CyberSync**
430
- - Parallel `walkDir` with 8 concurrent subdirectory scans
431
- - Hash batch size doubled (50 → 100)
432
- - Reconcile interval: 2min (was 5min)
433
- - Timing in reconcile logs
434
-
435
- **Output**
436
- - Compact `ok()` / `fail()` helpers for cleaner Claude Code results
437
- - `mesh_status` outputs aligned table with column headers
438
- - `node_info` shows which host path is active (WG/Tailscale/Public)
439
- - `exec` and `run` use `label` field as display tag
440
-
441
- **CyberBase Integration**
442
- - Renamed PostgreSQL database from `cybersync` to `cyberbase` (single DB for everything)
443
- - VaultBridge: mirrors all sync items, knowledge, and memory to Obsidian-compatible markdown
444
- - Obsidian vault at `~/Documents/BuisnessProjects/CyberBase` with Obsidian Sync for cloud backup
445
- - Daily event logs in `vault/logs/`
446
- - `obsidian-mcp` deployed on all mesh nodes for AI vault access
447
-
448
- ---
449
-
450
- ## Architecture
451
-
452
- ```
453
- omniwire/
454
- src/
455
- mcp/ MCP server (40 tools, 3 transports)
456
- nodes/ SSH2 pool, transfer engine, PTY, tunnels
457
- sync/ CyberSync + CyberBase (PostgreSQL, Obsidian vault, encryption)
458
- protocol/ Mesh config, types, path parsing
459
- commands/ Interactive REPL
460
- ui/ Terminal formatting
461
- ```
462
-
463
- ---
464
-
465
- ## Requirements
466
-
467
- - **Node.js** >= 20
468
- - **SSH access** to remote nodes (key-based auth)
469
- - **PostgreSQL** (only for CyberSync)
470
- - **WireGuard + Tailscale** recommended (multi-path failover uses both)
471
- - **Obsidian** (optional) for CyberBase vault browsing + Obsidian Sync cloud backup
472
-
473
- ---
474
-
475
- <p align="center">
476
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E6B450?style=flat-square&labelColor=0A0E14" alt="MIT License" /></a>
477
- </p>
478
-
479
- <p align="center">
480
- <picture>
481
- <source media="(prefers-color-scheme: dark)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:0A0E14,50:1A1F2E,100:59C2FF&height=100&section=footer" />
482
- <source media="(prefers-color-scheme: light)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:E8EAED,50:D4D8DE,100:59C2FF&height=100&section=footer" />
483
- <img alt="footer" src="https://capsule-render.vercel.app/api?type=waving&color=0:0A0E14,50:1A1F2E,100:59C2FF&height=100&section=footer" />
484
- </picture>
485
- </p>
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://capsule-render.vercel.app/api?type=venom&color=0:0A0E14,50:0D1B2A,100:1B2838&height=220&section=header&text=OmniWire&fontSize=80&fontColor=59C2FF&animation=fadeIn&fontAlignY=32&desc=Multi-Agent%20Mesh%20Control%20%E2%80%94%2053%20MCP%20Tools%20%C2%B7%20A2A%20Protocol%20%C2%B7%20~80ms%20Latency&descSize=16&descColor=8B949E&descAlignY=58" />
4
+ <source media="(prefers-color-scheme: light)" srcset="https://capsule-render.vercel.app/api?type=venom&color=0:E8EAED,50:D4D8DE,100:59C2FF&height=220&section=header&text=OmniWire&fontSize=80&fontColor=0A0E14&animation=fadeIn&fontAlignY=32&desc=Multi-Agent%20Mesh%20Control%20%E2%80%94%2053%20MCP%20Tools%20%C2%B7%20A2A%20Protocol%20%C2%B7%20~80ms%20Latency&descSize=16&descColor=586069&descAlignY=58" />
5
+ <img alt="OmniWire" src="https://capsule-render.vercel.app/api?type=venom&color=0:0A0E14,50:0D1B2A,100:1B2838&height=220&section=header&text=OmniWire&fontSize=80&fontColor=59C2FF&animation=fadeIn&fontAlignY=32&desc=Multi-Agent%20Mesh%20Control%20%E2%80%94%2053%20MCP%20Tools%20%C2%B7%20A2A%20Protocol%20%C2%B7%20~80ms%20Latency&descSize=16&descColor=8B949E&descAlignY=58" />
6
+ </picture>
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/omniwire"><img src="https://img.shields.io/npm/v/omniwire?style=for-the-badge&logo=npm&color=CB3837&labelColor=0A0E14" alt="npm" /></a>
11
+ <img src="https://img.shields.io/badge/MCP-53_tools-59C2FF?style=for-the-badge&labelColor=0A0E14" alt="tools" />
12
+ <img src="https://img.shields.io/badge/A2A-protocol-00C853?style=for-the-badge&labelColor=0A0E14" alt="A2A" />
13
+ <img src="https://img.shields.io/badge/latency-~80ms-FF6D00?style=for-the-badge&labelColor=0A0E14" alt="latency" />
14
+ <img src="https://img.shields.io/badge/lz4-transfer-CC93E6?style=for-the-badge&labelColor=0A0E14" alt="lz4" />
15
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-8B949E?style=for-the-badge&labelColor=0A0E14" alt="license" /></a>
16
+ </p>
17
+
18
+ <br/>
19
+
20
+ <p align="center">
21
+ <b>The infrastructure layer for AI agent swarms.</b>
22
+ </p>
23
+
24
+ <p align="center">
25
+ 53 MCP tools &bull; Agent-to-Agent messaging &bull; Distributed task queues &bull; Capability routing<br/>
26
+ AES-128-GCM SSH2 &bull; LZ4 transfers &bull; Circuit breakers &bull; Multi-path failover<br/>
27
+ Session chaining &bull; Pipeline DAGs &bull; Blackboard architecture &bull; Event pub/sub
28
+ </p>
29
+
30
+ <br/>
31
+
32
+ > **v2.5** &mdash; AES-128-GCM cipher preference, 2s keepalive, LZ4 compression, `shuf` port finder, SFTP-first reads, agent registry, blackboard, task queues, capability routing. See [changelog](#changelog).
33
+
34
+ <br/>
35
+
36
+ ---
37
+
38
+ ## Quick Start
39
+
40
+ ```bash
41
+ npm install -g omniwire
42
+ ```
43
+
44
+ Add to your AI agent (Claude Code, Cursor, OpenCode, etc.):
45
+
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "omniwire": { "command": "omniwire", "args": ["--stdio"] }
50
+ }
51
+ }
52
+ ```
53
+
54
+ ---
55
+
56
+ ## Why OmniWire?
57
+
58
+ | Problem | OmniWire Solution |
59
+ |---------|-------------------|
60
+ | Managing multiple servers manually | One tool call controls any node |
61
+ | Agents can't coordinate with each other | A2A messaging, events, semaphores |
62
+ | Multi-step deploys need many round-trips | Pipelines chain steps in 1 call |
63
+ | Flaky commands break agent loops | Built-in retry + assert + watch |
64
+ | Long tasks block the agent | Background dispatch with task IDs |
65
+ | Results lost between tool calls | Session store with `{{key}}` interpolation |
66
+ | Different transfer methods for diff sizes | Auto-selects SFTP / netcat / aria2c |
67
+ | SSH connections drop | Multi-path failover + circuit breaker |
68
+
69
+ ---
70
+
71
+ ## Architecture
72
+
73
+ ```mermaid
74
+ graph TB
75
+ subgraph clients["AI Agents"]
76
+ CC["Claude Code"]
77
+ OC["OpenCode / OpenClaw"]
78
+ CU["Cursor / Any MCP Client"]
79
+ A2["Other Agents (A2A)"]
80
+ end
81
+
82
+ subgraph omniwire["OmniWire MCP Server"]
83
+ direction TB
84
+ MCP["MCP Protocol Layer<br/>stdio | SSE | REST"]
85
+
86
+ subgraph tools["53 Tools"]
87
+ direction LR
88
+ EXEC["Execution<br/>exec run batch<br/>broadcast pipeline"]
89
+ AGENT["Agentic<br/>store watch task<br/>a2a events locks"]
90
+ FILES["Files & Deploy<br/>read write transfer<br/>deploy find"]
91
+ SYS["System & DevOps<br/>docker services<br/>cron env git syslog"]
92
+ SYNC["CyberSync<br/>sync diff search<br/>secrets knowledge"]
93
+ end
94
+
95
+ subgraph engine["Core Engine"]
96
+ direction LR
97
+ POOL["SSH2 Pool<br/>persistent compressed<br/>circuit breaker"]
98
+ XFER["Transfer Engine<br/>SFTP netcat+gzip<br/>aria2c 16-conn"]
99
+ CSYNC["Sync Engine<br/>PostgreSQL XChaCha20<br/>parallel reconcile"]
100
+ end
101
+ end
102
+
103
+ subgraph mesh["Infrastructure Mesh"]
104
+ direction LR
105
+ N1["Node A<br/>storage"]
106
+ N2["Node B<br/>compute"]
107
+ N3["Node C<br/>GPU"]
108
+ N4["Node D<br/>local"]
109
+ end
110
+
111
+ DB[("PostgreSQL<br/>CyberBase")]
112
+
113
+ CC & OC & CU & A2 -->|MCP| MCP
114
+ MCP --> tools
115
+ tools --> engine
116
+ POOL -->|"SSH2 multi-path"| N1 & N2 & N3
117
+ POOL -->|"local exec"| N4
118
+ CSYNC --> DB
119
+
120
+ style omniwire fill:#0A0E14,stroke:#59C2FF,stroke-width:2px,color:#C6D0E1
121
+ style clients fill:#1A1F2E,stroke:#91B362,stroke-width:1px,color:#C6D0E1
122
+ style mesh fill:#1A1F2E,stroke:#E6B450,stroke-width:1px,color:#C6D0E1
123
+ style tools fill:#141922,stroke:#59C2FF,stroke-width:1px,color:#C6D0E1
124
+ style engine fill:#141922,stroke:#CC93E6,stroke-width:1px,color:#C6D0E1
125
+ style MCP fill:#1A1F2E,stroke:#59C2FF,color:#59C2FF
126
+ style DB fill:#1A1F2E,stroke:#CC93E6,color:#CC93E6
127
+ ```
128
+
129
+ ---
130
+
131
+ ## Key Capabilities
132
+
133
+ <table>
134
+ <tr>
135
+ <td width="50%">
136
+
137
+ ### Execution
138
+ ```
139
+ omniwire_exec single command + retry + assert
140
+ omniwire_run multi-line script (compact UI)
141
+ omniwire_batch N commands, 1 tool call, chaining
142
+ omniwire_broadcast parallel across all nodes
143
+ omniwire_pipeline multi-step DAG with data flow
144
+ ```
145
+
146
+ </td>
147
+ <td width="50%">
148
+
149
+ ### Multi-Agent (A2A)
150
+ ```
151
+ omniwire_store session key-value store
152
+ omniwire_a2a_message agent-to-agent queues
153
+ omniwire_event pub/sub event bus
154
+ omniwire_semaphore distributed locking
155
+ omniwire_agent_task async background dispatch
156
+ omniwire_workflow reusable named DAGs
157
+ ```
158
+
159
+ </td>
160
+ </tr>
161
+ <tr>
162
+ <td>
163
+
164
+ ### Adaptive File Transfer
165
+ ```
166
+ < 10 MB SFTP native, 80ms
167
+ 10M-1GB netcat+gzip compressed, 100ms
168
+ > 1 GB aria2c 16-parallel, max speed
169
+ ```
170
+
171
+ </td>
172
+ <td>
173
+
174
+ ### Connection Resilience
175
+ ```
176
+ Connected --> Health Ping (30s, parallel)
177
+ |
178
+ Failure --> Multi-path Failover
179
+ | WireGuard -> Tailscale -> Public IP
180
+ |
181
+ +--> Retry (500ms -> 1s -> ... -> 15s)
182
+ |
183
+ 3 fails --> Circuit OPEN (20s) -> Auto-recover
184
+ ```
185
+
186
+ </td>
187
+ </tr>
188
+ <tr>
189
+ <td>
190
+
191
+ ### Agentic Chaining
192
+ ```
193
+ exec(store_as="ip") store result
194
+ exec(command="ping {{ip}}") interpolate
195
+ batch(abort_on_fail=true) fail-fast
196
+ exec(format="json") structured output
197
+ exec(retry=3, assert="ok") resilient
198
+ watch(assert="ready") poll until
199
+ ```
200
+
201
+ </td>
202
+ <td>
203
+
204
+ ### CyberSync + CyberBase
205
+ ```
206
+ Nodes --push--> PostgreSQL (cyberbase)
207
+ | |
208
+ | XChaCha20-Poly1305
209
+ | encrypted at rest
210
+ |
211
+ +--mirror--> Obsidian Vault
212
+ |
213
+ Obsidian Sync (cloud)
214
+ ```
215
+
216
+ </td>
217
+ </tr>
218
+ </table>
219
+
220
+ ---
221
+
222
+ ## All 53 Tools
223
+
224
+ ### Execution (5)
225
+
226
+ | Tool | Description |
227
+ |------|-------------|
228
+ | `omniwire_exec` | Run command on any node. `retry`, `assert`, `store_as`, `format:"json"`, `{{key}}` interpolation. |
229
+ | `omniwire_run` | Execute multi-line scripts via temp file. Keeps tool call UI clean. |
230
+ | `omniwire_batch` | N commands in 1 call. Chaining with `{{prev}}`, `abort_on_fail`, parallel or sequential. |
231
+ | `omniwire_broadcast` | Execute on all nodes simultaneously. JSON format support. |
232
+ | `omniwire_pipeline` | Multi-step DAG. `{{prev}}`/`{{stepN}}` interpolation, per-step error handling, cross-node. |
233
+
234
+ ### Agentic / A2A (13)
235
+
236
+ | Tool | Description |
237
+ |------|-------------|
238
+ | `omniwire_store` | Session key-value store. Persist results across tool calls for chaining. |
239
+ | `omniwire_watch` | Poll command until assert pattern matches. For deploys, builds, service readiness. |
240
+ | `omniwire_healthcheck` | Parallel health probe across all nodes (connectivity, disk, mem, load, docker). Single call. |
241
+ | `omniwire_agent_task` | Dispatch background tasks. Get task IDs, poll status, retrieve results. A2A async. |
242
+ | `omniwire_a2a_message` | Agent-to-agent message queues. Send/receive/peek on named channels. |
243
+ | `omniwire_semaphore` | Distributed locking. Atomic acquire/release to prevent race conditions. |
244
+ | `omniwire_event` | Pub/sub events. Emit/poll timestamped events per topic. ACP/A2A/ACPX compatible. |
245
+ | `omniwire_workflow` | Define and run reusable named workflows (DAGs). Stored on disk, triggered by any agent. |
246
+ | `omniwire_agent_registry` | Register/discover agents by capabilities. Dynamic A2A routing. Heartbeat. |
247
+ | `omniwire_blackboard` | Shared blackboard for agent swarms. Post findings, read, search across topics. |
248
+ | `omniwire_task_queue` | Distributed task queue. Enqueue/dequeue with priorities. Complete/fail reporting. |
249
+ | `omniwire_capability` | Query node capabilities (tools, runtimes, GPU). Intelligent task routing. |
250
+
251
+ ### Files & Transfer (6)
252
+
253
+ | Tool | Description |
254
+ |------|-------------|
255
+ | `omniwire_read_file` | Read file from any node. `node:/path` format. |
256
+ | `omniwire_write_file` | Write/create file on any node. |
257
+ | `omniwire_list_files` | List directory contents. |
258
+ | `omniwire_find_files` | Glob search across all nodes. |
259
+ | `omniwire_transfer_file` | Copy between nodes. Auto-selects SFTP/netcat/aria2c. |
260
+ | `omniwire_deploy` | Deploy file from one node to all others in parallel. |
261
+
262
+ ### Monitoring (3)
263
+
264
+ | Tool | Description |
265
+ |------|-------------|
266
+ | `omniwire_mesh_status` | Health, latency, CPU/mem/disk for all nodes. Tabular output. |
267
+ | `omniwire_node_info` | Detailed info for a specific node. |
268
+ | `omniwire_live_monitor` | Snapshot metrics: cpu, memory, disk, network. |
269
+
270
+ ### System & DevOps (12)
271
+
272
+ | Tool | Description |
273
+ |------|-------------|
274
+ | `omniwire_process_list` | List/filter processes across nodes |
275
+ | `omniwire_disk_usage` | Disk usage for all nodes |
276
+ | `omniwire_tail_log` | Last N lines of a log file |
277
+ | `omniwire_install_package` | Install via apt/npm/pip |
278
+ | `omniwire_service_control` | systemd start/stop/restart/status |
279
+ | `omniwire_docker` | Docker commands on any node |
280
+ | `omniwire_kernel` | dmesg, sysctl, modprobe, lsmod, strace, perf |
281
+ | `omniwire_cron` | List/add/remove cron jobs |
282
+ | `omniwire_env` | Get/set persistent environment variables |
283
+ | `omniwire_network` | ping, traceroute, dns, ports, speed, connections |
284
+ | `omniwire_git` | Git commands on repos on any node |
285
+ | `omniwire_syslog` | Query journalctl with filters |
286
+
287
+ ### Network & Misc (5)
288
+
289
+ | Tool | Description |
290
+ |------|-------------|
291
+ | `omniwire_port_forward` | Create/list/close SSH tunnels |
292
+ | `omniwire_open_browser` | Open URL in browser on a node |
293
+ | `omniwire_shell` | Persistent PTY session (preserves cwd/env) |
294
+ | `omniwire_stream` | Capture streaming output (tail -f, watch) |
295
+ | `omniwire_clipboard` | Shared clipboard buffer across mesh |
296
+
297
+ ### CyberSync (9)
298
+
299
+ | Tool | Description |
300
+ |------|-------------|
301
+ | `cybersync_status` | Sync status, item counts, pending syncs |
302
+ | `cybersync_sync_now` | Trigger immediate reconciliation |
303
+ | `cybersync_diff` | Show local vs database differences |
304
+ | `cybersync_history` | Query sync event log |
305
+ | `cybersync_search_knowledge` | Full-text search unified knowledge base |
306
+ | `cybersync_get_memory` | Retrieve Claude memory from PostgreSQL |
307
+ | `cybersync_manifest` | Show tracked files per tool |
308
+ | `cybersync_force_push` | Force push file to all nodes |
309
+ | `omniwire_secrets` | Get/set/delete/list/sync secrets (1Password, file, env) |
310
+ | `omniwire_update` | Self-update OmniWire |
311
+
312
+ ---
313
+
314
+ ## Performance
315
+
316
+ | Operation | Latency | v2.5 Optimization |
317
+ |-----------|---------|-------------------|
318
+ | **Command exec** | **~80ms** | AES-128-GCM cipher, persistent SSH2 channel, zero-fork `:` ping |
319
+ | **Mesh status** | **~100ms** | Parallel probes, 5s cache, single `/proc` read (no pipes) |
320
+ | **File read (<1MB)** | **~60ms** | SFTP-first path (skips `cat` shell fork) |
321
+ | **Transfer (10MB)** | **~120ms** | LZ4 compression (10x faster than gzip), 50ms bind delay |
322
+ | **Transfer (1GB)** | **~8s** | aria2c 16-connection parallel, 150ms server startup |
323
+ | **Pipeline (5 steps)** | **~400ms** | `{{prev}}` interpolation, no extra tool calls |
324
+ | **Health check (all)** | **~90ms** | Parallel Promise.allSettled, structured JSON |
325
+ | **A2A message** | **~85ms** | File-append queue, atomic dequeue |
326
+ | **Config push** | **~150ms** | Parallel deploy + Obsidian mirror |
327
+ | **Reconnect** | **~300ms** | 300ms initial delay (was 500ms), 2s keepalive detection |
328
+
329
+ **Optimizations in v2.5:**
330
+ - **Cipher**: AES-128-GCM (AES-NI accelerated) preferred over default negotiation
331
+ - **Key exchange**: curve25519-sha256 preferred (fastest modern KEX)
332
+ - **Keepalive**: 2s interval, 2 retries = 4s dead detection (was 6s)
333
+ - **Port finder**: `shuf` (pure bash) replaces `python3 -c socket` (saves ~30ms per transfer)
334
+ - **Compression**: LZ4-1 for transfers (10x faster than gzip, ~same ratio for mixed data)
335
+ - **Buffer**: Array push + join replaces string concatenation (O(n) vs O(n^2) for large outputs)
336
+ - **Status**: Single `/proc` read replaces multiple piped commands
337
+ - **Health ping**: `:` builtin replaces `true` (no hash lookup, no fork)
338
+ - **Reads**: SFTP subsystem tried first, falls back to `cat` only on failure
339
+ - **Circuit breaker**: 15s recovery (was 20s), 10s reconnect cap (was 15s)
340
+
341
+ ---
342
+
343
+ ## Security
344
+
345
+ - All remote execution via `ssh2.Client.exec()` -- never `child_process.exec()`
346
+ - Key-based auth only, no passwords stored, SSH key caching
347
+ - Multi-path failover: WireGuard -> Tailscale -> Public IP
348
+ - XChaCha20-Poly1305 at-rest encryption for synced configs
349
+ - 2MB output guard prevents memory exhaustion
350
+ - 4KB auto-truncation prevents context window bloat
351
+ - Circuit breaker with 20s auto-recovery isolates failing nodes
352
+ - CORS restricted to localhost on REST API
353
+
354
+ ---
355
+
356
+ ## Transport Modes
357
+
358
+ | Mode | Port | Use Case |
359
+ |------|------|----------|
360
+ | `--stdio` | -- | Claude Code, Cursor, MCP subprocess |
361
+ | `--sse-port=N` | 3200 | OpenCode, remote HTTP MCP clients |
362
+ | `--rest-port=N` | 3201 | Scripts, dashboards, non-MCP |
363
+
364
+ ```bash
365
+ omniwire --stdio # MCP mode (default)
366
+ omniwire --sse-port=3200 --rest-port=3201 # HTTP mode
367
+ omniwire --stdio --no-sync # MCP without CyberSync
368
+ omniwire # or: ow # Interactive REPL
369
+ ```
370
+
371
+ ---
372
+
373
+ ## Configure Mesh
374
+
375
+ Create `~/.omniwire/mesh.json`:
376
+
377
+ ```json
378
+ {
379
+ "nodes": [
380
+ { "id": "server1", "host": "10.0.0.1", "user": "root", "identityFile": "id_ed25519", "role": "storage" },
381
+ { "id": "server2", "host": "10.0.0.2", "user": "root", "identityFile": "id_ed25519", "role": "compute" }
382
+ ]
383
+ }
384
+ ```
385
+
386
+ ---
387
+
388
+ ## Changelog
389
+
390
+ <details>
391
+ <summary><b>v2.5.0 -- Performance Overhaul, A2A Protocol Expansion</b></summary>
392
+
393
+ **Performance**: AES-128-GCM cipher, curve25519-sha256 KEX, 2s keepalive, LZ4 transfers (10x faster), `shuf` port finder (-30ms), SFTP-first reads, array buffer concat, `/proc` single-read status, `:` builtin health ping, 300ms reconnect start, 15s circuit breaker.
394
+
395
+ **4 new A2A tools** (49 -> 53): agent_registry (capability discovery), blackboard (swarm collaboration), task_queue (distributed work), capability (node routing).
396
+
397
+ **Connectivity**: Always-on 2s keepalive with 4s dead detection. 5s connect timeout. 10s reconnect cap. 15s circuit recovery.
398
+
399
+ </details>
400
+
401
+ <details>
402
+ <summary><b>v2.4.0 -- Agentic Loop, A2A, Multi-Agent Orchestration</b></summary>
403
+
404
+ **9 new agentic tools** (40 -> 49): store, pipeline, watch, healthcheck, agent_task, a2a_message, semaphore, event, workflow
405
+
406
+ **Agentic upgrades to existing tools**: `format:"json"`, `retry`, `assert`, `store_as`, `{{key}}` interpolation on exec/broadcast/batch
407
+
408
+ **Dynamic response processing**: Structured JSON output, step-to-step data flow, session result store, abort-on-fail chains
409
+
410
+ </details>
411
+
412
+ <details>
413
+ <summary><b>v2.3.0 -- Compact Output, Speed, New Tools</b></summary>
414
+
415
+ Output overhaul (auto-truncation, smart time, tabular multi-node). Performance (parallel health pings, 3s keepalive, 20s circuit breaker, 6s connect timeout). 6 new DevOps tools (cron, env, network, clipboard, git, syslog).
416
+
417
+ </details>
418
+
419
+ <details>
420
+ <summary><b>v2.2.1 -- Security & Bug Fixes</b></summary>
421
+
422
+ Fixed script-only exec, shell race condition, transfer size guard, CORS restriction, input validation.
423
+
424
+ </details>
425
+
426
+ <details>
427
+ <summary><b>v2.1.0 -- Multi-Path Failover & Performance</b></summary>
428
+
429
+ Multi-path SSH (WireGuard/Tailscale/Public), SSH key caching, CyberBase integration, VaultBridge Obsidian mirror.
430
+
431
+ </details>
432
+
433
+ ---
434
+
435
+ ## Architecture
436
+
437
+ ```
438
+ omniwire/
439
+ src/
440
+ mcp/ MCP server (53 tools, 3 transports)
441
+ nodes/ SSH2 pool, transfer engine, PTY, tunnels
442
+ sync/ CyberSync + CyberBase (PostgreSQL, Obsidian, encryption)
443
+ protocol/ Mesh config, types, path parsing
444
+ commands/ Interactive REPL
445
+ ui/ Terminal formatting
446
+ ```
447
+
448
+ ## Requirements
449
+
450
+ - **Node.js** >= 20
451
+ - **SSH access** to remote nodes (key-based auth)
452
+ - **PostgreSQL** (only for CyberSync)
453
+ - **WireGuard + Tailscale** recommended (multi-path failover)
454
+
455
+ ---
456
+
457
+ <p align="center">
458
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E6B450?style=flat-square&labelColor=0A0E14" alt="MIT License" /></a>
459
+ </p>
460
+
461
+ <p align="center">
462
+ <picture>
463
+ <source media="(prefers-color-scheme: dark)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:0A0E14,50:1A1F2E,100:59C2FF&height=100&section=footer" />
464
+ <source media="(prefers-color-scheme: light)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:E8EAED,50:D4D8DE,100:59C2FF&height=100&section=footer" />
465
+ <img alt="footer" src="https://capsule-render.vercel.app/api?type=waving&color=0:0A0E14,50:1A1F2E,100:59C2FF&height=100&section=footer" />
466
+ </picture>
467
+ </p>