omniwire-mcp

The infrastructure layer for AI agent swarms.

81 MCP tools · A2A protocol · OmniMesh VPN · nftables firewall · CDP browser · cookie sync · CyberBase persistence

---

Quick Start

npm install -g omniwire

Add to your AI agent (Claude Code, Cursor, OpenCode, etc.):

{
  "mcpServers": {
    "omniwire": { "command": "omniwire", "args": ["--stdio"] }
  }
}

---

Why OmniWire?

Problem	OmniWire Solution
Managing multiple servers manually	One tool call controls any node
Agents can't coordinate with each other	A2A messaging, events, semaphores
Multi-step deploys need many round-trips	Pipelines chain steps in 1 call
Flaky commands break agent loops	Built-in retry + assert + watch
Long tasks block the agent	background: true on any tool
Results lost between tool calls	Session store with {{key}} interpolation
Different transfer methods for diff sizes	Auto-selects SFTP / netcat+LZ4 / aria2c
SSH connections drop	Multi-path failover + circuit breaker

---

Use Cases

DevOps & Infrastructure

# Deploy to all nodes in one call
omniwire_deploy(src="contabo:/app/v2.tar.gz", dst="/opt/app/")

# Rolling service restart
omniwire_batch([
  {node: "node1", command: "systemctl restart app"},
  {node: "node2", command: "systemctl restart app"}
], parallel=false)

# Monitor disk across fleet
omniwire_disk_usage()

Security & Pentesting

# Anonymous nmap through Mullvad VPN
omniwire_exec(
  node="contabo",
  command="nmap -sV -T4 target.com",
  via_vpn="mullvad:se",
  background=true
)

# Rotate exit IP between scans
omniwire_vpn(action="rotate", node="contabo")

# Run nuclei through VPN namespace
omniwire_exec(command="nuclei -u target.com",
  via_vpn="mullvad", store_as="nuclei_results")

Multi-Agent Coordination

# Agent A dispatches work
omniwire_task_queue(action="enqueue",
  queue="recon", task="subfinder -d target.com")

# Agent B picks it up
omniwire_task_queue(action="dequeue", queue="recon")

# Share findings on blackboard
omniwire_blackboard(action="post",
  topic="subdomains", data="api.target.com")

# A2A messaging between agents
omniwire_a2a_message(action="send",
  channel="results", message="scan complete")

Background & Async Workflows

# Long build in background
omniwire_exec(
  command="docker build -t app .",
  node="contabo", background=true
)
# Returns: "BACKGROUND bg-abc123"

# Check progress
omniwire_bg(action="poll", task_id="bg-abc123")
# Returns: "RUNNING (45.2s)"

# Get result when done
omniwire_bg(action="result", task_id="bg-abc123")

# Pipeline: build → test → deploy
omniwire_pipeline(steps=[
  {node: "contabo", command: "make build"},
  {node: "contabo", command: "make test"},
  {command: "deploy.sh", store_as: "version"}
])

File Operations

# Transfer large dataset between nodes
omniwire_transfer_file(
  src="contabo:/data/model.bin",
  dst="hostinger:/ml/model.bin"
)
# Auto-selects: aria2c (16-conn parallel)

# Sync config to all nodes
omniwire_deploy(
  src_node="contabo",
  src_path="/etc/nginx/nginx.conf",
  dst_path="/etc/nginx/nginx.conf"
)

VPN & Anonymous Operations

# Full Mullvad setup for a node
omniwire_vpn(action="connect", server="se",
  node="contabo")
omniwire_vpn(action="quantum", config="on")
omniwire_vpn(action="daita", config="on")
omniwire_vpn(action="multihop", config="se:us")
omniwire_vpn(action="dns", config="adblock")
omniwire_vpn(action="killswitch", config="on")

# Verify anonymous IP
omniwire_vpn(action="ip", node="contabo")

# Node-wide VPN (mesh stays connected)
omniwire_vpn(action="full-on", server="de")

---

Architecture

graph TB
    subgraph clients["AI Agents"]
        CC["Claude Code"]
        OC["OpenCode / OpenClaw"]
        CU["Cursor / Any MCP Client"]
        A2["Other Agents (A2A)"]
    end

    subgraph omniwire["OmniWire MCP Server"]
        direction TB
        MCP["MCP Protocol Layer<br/>stdio | SSE | REST"]

        subgraph tools["81 Tools"]
            direction LR
            EXEC["Execution<br/>exec  run  batch<br/>broadcast  pipeline  bg"]
            AGENT["Agentic<br/>store  watch  task<br/>a2a  events  locks"]
            FILES["Files & Deploy<br/>read  write  transfer<br/>deploy  find"]
            SYS["System & DevOps<br/>docker  services<br/>cron  env  git  syslog"]
            SYNC["CyberSync<br/>sync  diff  search<br/>secrets  knowledge"]
        end

        subgraph engine["Core Engine"]
            direction LR
            POOL["SSH2 Pool<br/>persistent  compressed<br/>circuit breaker"]
            XFER["Transfer Engine<br/>SFTP  netcat+LZ4<br/>aria2c 16-conn"]
            CSYNC["Sync Engine<br/>PostgreSQL  XChaCha20<br/>parallel reconcile"]
        end
    end

    subgraph mesh["Infrastructure Mesh"]
        direction LR
        N1["Node A<br/>storage"]
        N2["Node B<br/>compute"]
        N3["Node C<br/>GPU"]
        N4["Node D<br/>local"]
    end

    DB[("PostgreSQL<br/>CyberBase")]

    CC & OC & CU & A2 -->|MCP| MCP
    MCP --> tools
    tools --> engine
    POOL -->|"SSH2 multi-path"| N1 & N2 & N3
    POOL -->|"local exec"| N4
    CSYNC --> DB

    style omniwire fill:#0D1117,stroke:#59C2FF,stroke-width:2px,color:#C6D0E1
    style clients fill:#161B22,stroke:#91B362,stroke-width:1px,color:#C6D0E1
    style mesh fill:#161B22,stroke:#E6B450,stroke-width:1px,color:#C6D0E1
    style tools fill:#0D1117,stroke:#59C2FF,stroke-width:1px,color:#C6D0E1
    style engine fill:#0D1117,stroke:#CC93E6,stroke-width:1px,color:#C6D0E1
    style MCP fill:#162B44,stroke:#59C2FF,color:#59C2FF
    style DB fill:#162B44,stroke:#CC93E6,color:#CC93E6

---

Key Capabilities

Execution

omniwire_exec       single command + retry + assert
omniwire_run        multi-line script (compact UI)
omniwire_batch      N commands, 1 tool call, chaining
omniwire_broadcast  parallel across all nodes
omniwire_pipeline   multi-step DAG with data flow
omniwire_bg         poll/list background tasks

Multi-Agent (A2A)

omniwire_store        session key-value store
omniwire_a2a_message  agent-to-agent queues
omniwire_event        pub/sub event bus
omniwire_semaphore    distributed locking
omniwire_agent_task   async background dispatch
omniwire_workflow     reusable named DAGs

Adaptive File Transfer

 < 10 MB   SFTP         native, 80ms
 10M-1GB   netcat+LZ4   compressed, 100ms
 > 1 GB    aria2c       16-parallel, max speed

Connection Resilience

Connected --> Health Ping (30s, parallel)
    |
Failure --> Multi-path Failover
    |         WireGuard -> Tailscale -> Public IP
    |
    +--> Retry (300ms -> 600ms -> ... -> 10s)
    |
3 fails --> Circuit OPEN (15s) -> Auto-recover

Background Dispatch

# Any tool supports background: true
exec(background=true)   -> "bg-abc123"
bg(action="poll", id=..) -> "RUNNING (3.2s)"
bg(action="result", id=..) -> full output
bg(action="list")       -> all tasks + status

Agentic Chaining

exec(store_as="ip")       store result
exec(command="ping {{ip}}") interpolate
batch(abort_on_fail=true)   fail-fast
exec(format="json")         structured output
exec(retry=3, assert="ok")  resilient
watch(assert="ready")       poll until

---

All 81 Tools

Every tool supports background: true — returns a task ID immediately. Poll with omniwire_bg.

Tool	Description
omniwire_exec	Run command on any node. retry, assert, store_as, format:"json", {{key}}, via_vpn.
omniwire_run	Multi-line scripts via temp file.
omniwire_batch	N commands in 1 call. Chaining {{prev}}, abort_on_fail, parallel/sequential.
omniwire_broadcast	Execute on all nodes simultaneously.
omniwire_pipeline	Multi-step DAG with {{prev}}/{{stepN}} interpolation.
omniwire_bg	List/poll/retrieve background task results.

Tool	Description
omniwire_store	Session key-value store for cross-call chaining.
omniwire_watch	Poll until assert matches — deploys, builds, readiness.
omniwire_healthcheck	Parallel health probe all nodes (disk, mem, load, docker).
omniwire_agent_task	Background task dispatch with poll/retrieve.
omniwire_a2a_message	Agent-to-agent message queues (send/receive/peek).
omniwire_semaphore	Distributed locking — atomic acquire/release.
omniwire_event	Pub/sub events per topic.
omniwire_workflow	Reusable named workflow DAGs.
omniwire_agent_registry	Agent capability discovery + heartbeat.
omniwire_blackboard	Shared blackboard for swarm coordination.
omniwire_task_queue	Distributed priority queue — enqueue/dequeue/complete.
omniwire_capability	Query node capabilities for intelligent routing.

Tool	Description
omniwire_read_file	Read file from any node (node:/path).
omniwire_write_file	Write/create file on any node.
omniwire_list_files	List directory contents.
omniwire_find_files	Glob search across nodes.
omniwire_transfer_file	Copy between nodes (auto SFTP/netcat/aria2c).
omniwire_deploy	Deploy one file to all nodes in parallel.

Tool	Description
omniwire_mesh_status	Health, latency, CPU/mem/disk — all nodes.
omniwire_node_info	Detailed info for one node.
omniwire_live_monitor	Snapshot metrics: cpu, memory, disk, network.

Tool	Description
omniwire_process_list	List/filter processes across nodes.
omniwire_disk_usage	Disk usage for all nodes.
omniwire_tail_log	Last N lines of a log file.
omniwire_install_package	Install via apt/npm/pip.
omniwire_service_control	systemd start/stop/restart/status.
omniwire_docker	Docker commands on any node.
omniwire_kernel	dmesg, sysctl, modprobe, lsmod, strace, perf.
omniwire_cron	List/add/remove cron jobs.
omniwire_env	Get/set persistent environment variables.
omniwire_network	ping, traceroute, dns, ports, speed, connections.
omniwire_git	Git commands on repos on any node.
omniwire_syslog	Query journalctl with filters.

Tool	Description
omniwire_firewall	nftables engine — presets, rate-limit, geo-block, port-knock, ban/unban. Mesh whitelisted.
omniwire_vpn	Mullvad/OpenVPN/WireGuard/Tailscale — multi-hop, DAITA, quantum, killswitch. Mesh-safe.
omniwire_cookies	Cookie management — JSON/Header/Netscape, browser extract, CyberBase + 1Password sync.
omniwire_cdp	Chrome DevTools Protocol — headless Chrome, screenshot, PDF, DOM, cookies.
omniwire_proxy	HTTP/SOCKS proxy management on any node.
omniwire_dns	DNS resolve, set server, flush cache, block domains.
omniwire_port_forward	SSH tunnels — create/list/close/mesh-expose.
omniwire_shell	Persistent PTY session (preserves cwd/env).
omniwire_clipboard	Shared clipboard buffer across mesh.

Tool	Description
omniwire_backup	Snapshot/restore paths. Diff, cleanup, retention.
omniwire_container	Docker lifecycle — compose, build, push, logs, prune, stats.
omniwire_cert	TLS certs — Let's Encrypt, check expiry, self-signed.
omniwire_user	User & SSH key management, sudo config.
omniwire_schedule	Distributed cron with failover.
omniwire_alert	Threshold alerting — disk/mem/load/offline + webhook notify.
omniwire_log_aggregate	Cross-node log search in parallel.
omniwire_benchmark	CPU/memory/disk/network benchmarks.
omniwire_stream	Capture streaming output (tail -f, watch).

Tool	Description
omniwire_omnimesh	WireGuard mesh manager — init/up/down/add-peer/sync-peers/health/rotate-keys/topology. All OS.
omniwire_mesh_expose	Expose localhost services to mesh — discover/expose/unexpose/expose-remote.
omniwire_mesh_gateway	Auto-expose all localhost services mesh-wide.
omniwire_events	Webhook + WebSocket + SSE event bus. Publish, manage webhooks, query log.
omniwire_knowledge	CyberBase knowledge CRUD, text/semantic search, health, vacuum, bulk-set, export.
omniwire_update	Self-update from npm + GitHub. Auto-update, mesh-wide push.

Tool	Description
omniwire_snippet	Reusable command templates with {{var}} substitution.
omniwire_alias	In-session command shortcuts.
omniwire_trace	Distributed tracing — span waterfalls across nodes.
omniwire_doctor	Health diagnostics — SSH, disk, mem, docker, WireGuard, CyberBase.
omniwire_metrics	Prometheus-compatible metrics scrape/export.
omniwire_audit	Command audit log — view/search/stats.
omniwire_plugin	Plugin system — list/load from ~/.omniwire/plugins/.

Tool	Description
cybersync_status	Sync status, item counts, pending syncs.
cybersync_sync_now	Trigger immediate reconciliation.
cybersync_diff	Local vs database differences.
cybersync_history	Sync event log.
cybersync_search_knowledge	Full-text search unified knowledge base.
cybersync_get_memory	Retrieve Claude memory from PostgreSQL.
cybersync_manifest	Tracked files per tool.
cybersync_force_push	Force push file to all nodes.
omniwire_secrets	Secrets management (1Password, file, env).

---

Performance

Operation	Latency	Optimization
Command exec	~80ms	AES-128-GCM cipher, persistent SSH2, zero-fork : ping
Mesh status	~100ms	Parallel probes, 5s cache, single /proc read
File read (<1MB)	~60ms	SFTP-first (skips cat fork)
Transfer (10MB)	~120ms	LZ4 compression (10x faster than gzip)
Transfer (1GB)	~8s	aria2c 16-connection parallel
Pipeline (5 steps)	~400ms	{{prev}} interpolation, no extra tool calls
Health check (all)	~90ms	Parallel Promise.allSettled
A2A message	~85ms	File-append queue, atomic dequeue
Reconnect	~300ms	300ms initial, 2s keepalive, 15s circuit breaker

• Cipher: AES-128-GCM (AES-NI hardware accelerated)
• Key exchange: curve25519-sha256 (fastest modern KEX)
• Keepalive: 2s interval, 2 retries = 4s dead detection
• Port finder: shuf (pure bash) replaces python3 -c socket (-30ms)
• Compression: LZ4-1 for transfers (10x faster than gzip)
• Buffer: Array push + join (O(n) vs O(n^2) string concat)
• Status: Single /proc read replaces multiple piped commands
• Health ping: : builtin (no hash lookup, no fork)
• Reads: SFTP tried first, cat fallback only on failure
• Circuit breaker: 15s recovery, 10s reconnect cap

---

Security

• All remote execution via ssh2.Client.exec() -- never child_process.exec()
• Key-based auth only, no passwords stored, SSH key caching
• Multi-path failover: WireGuard -> Tailscale -> Public IP
• XChaCha20-Poly1305 at-rest encryption for synced configs
• 2MB output guard prevents memory exhaustion
• 4KB auto-truncation prevents context window bloat
• Circuit breaker isolates failing nodes
• CORS restricted to localhost on REST API

---

Transport Modes

Mode	Port	Use Case
--stdio	--	Claude Code, Cursor, MCP subprocess
--sse-port=N	3200	OpenCode, remote HTTP MCP clients
--rest-port=N	3201	Scripts, dashboards, non-MCP

omniwire --stdio                          # MCP mode (default)
omniwire --sse-port=3200 --rest-port=3201 # HTTP mode
omniwire --stdio --no-sync               # MCP without CyberSync
omniwire    # or: ow                      # Interactive REPL

---

Configure Mesh

Create ~/.omniwire/mesh.json:

{
  "nodes": [
    { "id": "server1", "host": "10.0.0.1", "user": "root", "identityFile": "id_ed25519", "role": "storage" },
    { "id": "server2", "host": "10.0.0.2", "user": "root", "identityFile": "id_ed25519", "role": "compute" }
  ]
}

---

Changelog

19 new tools: proxy, dns, backup, container, cert, user, schedule, alert, log_aggregate, benchmark, snippet, alias, trace, doctor, metrics, audit, plugin, cookies, cdp.

CyberBase auto-persistence: Store, audit, blackboard, cookies all sync to PostgreSQL. pgvector semantic search. 5s statement_timeout on all DB calls.

Architecture: Priority command queues, smart output truncation, predictive node selection, latency history, connection pool stats.

Security: Command denylist (blocks rm -rf /, fork bombs, disk wipes). Audit log with CyberBase persistence.

A2A: Typed message schemas (JSON validation), dead letter queue for failed tasks, pub/sub event filters.

DX: GitHub Actions CI, bash/zsh/fish shell completions, --json flag, cookie sync to 1Password.

omniwire_firewall: nftables-based firewall engine with 17 actions. Presets (server, paranoid, minimal, pentest), rate-limiting, geo-blocking by country, port-knocking sequences, IP ban/unban, whitelist/blacklist, rule management, audit log, save/restore.

Zero mesh impact: wg0, wg1, tailscale0, and all mesh CIDRs (10.10.0.0/24, 10.20.0.0/24, 100.64.0.0/10) are always whitelisted before any hardening rules. nftables runs in kernel space — zero latency overhead.

omniwire_vpn tool: Mullvad, OpenVPN, WireGuard, Tailscale. Split-tunnel (per-command) + full-node modes. Mesh connectivity (wg0, wg1, Tailscale) always preserved via route exclusions and network namespace isolation.

via_vpn on exec: Route any command through VPN using Linux network namespaces. Only the command's traffic goes through VPN — SSH/WireGuard mesh stays on real interface.

Modes: connect (split-tunnel), full-on (node-wide with mesh exclusions), rotate (new exit IP), status, list, ip.

background: true auto-injected into all 81 tools via server-level wrapper. Returns task ID, poll with omniwire_bg. New omniwire_bg tool for list/poll/result.

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.

4 new A2A tools (49 -> 53): agent_registry (capability discovery), blackboard (swarm collaboration), task_queue (distributed work), capability (node routing).

9 new agentic tools (40 -> 49): store, pipeline, watch, healthcheck, agent_task, a2a_message, semaphore, event, workflow. Agentic upgrades: format:"json", retry, assert, store_as, {{key}} interpolation.

Output overhaul (auto-truncation, smart time, tabular multi-node). 6 new DevOps tools (cron, env, network, clipboard, git, syslog).

Security fixes, multi-path SSH failover, CyberBase integration, VaultBridge Obsidian mirror.

---

omniwire/
  src/
    mcp/           MCP server (81 tools, 3 transports)
    nodes/         SSH2 pool, transfer engine, PTY, tunnels
    sync/          CyberSync + CyberBase (PostgreSQL, Obsidian, encryption)
    protocol/      Mesh config, types, path parsing
    commands/      Interactive REPL
    ui/            Terminal formatting

Requirements: Node.js >= 20 • SSH key access to nodes • PostgreSQL (CyberSync only) • WireGuard recommended

---