omniwire

Quick Start

npm install -g omniwire

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

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

Why OmniWire?

Use Cases

# Deploy to all nodes in one call
omniwire_deploy(src="node-a:/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()

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

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

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

# 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")

# Long build in background
omniwire_exec(
  command="docker build -t app .",
  node="node-a", 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: "node-a", command: "make build"},
  {node: "node-a", command: "make test"},
  {command: "deploy.sh", store_as: "version"}
])

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

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

# Full Mullvad setup for a node
omniwire_vpn(action="connect", server="se",
  node="node-a")
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="node-a")

# 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["88 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

Agent Setup Instructions

OpenClaw

OmniWire is available as a ClawHub skill:

# Install via ClawHub CLI
clawhub install omniwire

# Or manual: copy integrations/openclaw/SKILL.md to your OpenClaw skills directory
cp integrations/openclaw/SKILL.md ~/.openclaw/skills/omniwire.md

CyberSync automatically ingests OpenClaw agents, skills, memory, and workspace into CyberBase PostgreSQL.

PaperClip

Register OmniWire as a zero-cost infrastructure agent:

{
  "agents": [{
    "name": "omniwire",
    "type": "local-cli",
    "command": "omniwire --stdio",
    "skills": ["mesh-exec", "file-transfer", "service-control", "docker", "vpn", "scraping", "firewall"],
    "budget": { "monthly_usd": 0 }
  }]
}

See integrations/paperclip/ for the full adapter and skill definition.

Claude Code

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

OpenCode / Oh-My-OpenAgent

{
  "mcp": {
    "omniwire": {
      "type": "local",
      "command": ["omniwire", "--stdio"]
    }
  }
}

Codex / Gemini

CyberSync automatically syncs OmniWire config to Codex and Gemini environments.

Key Capabilities

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

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

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

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

# 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

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 88 Tools

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

Performance

• 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
• Secret-bearing tool output is redacted by default (omniwire_env lists keys, not values)
• Prefer 1Password or another managed vault for production secrets; file/env backends are local-development fallbacks
• 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

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" }
  ]
}

Agentic Installation / Setup

For adding a new node to your OmniWire mesh — what to have ready, how to wire it in, and how to connect it to Claude Code.

Prerequisites

Install OmniWire

npm install -g omniwire
omniwire --version   # verify

Add a New Node

1. Generate WireGuard keypair on the new node:

wg genkey | tee /etc/wireguard/node_private.key | wg pubkey > /etc/wireguard/node_pub.key
cat /etc/wireguard/node_pub.key

2. Assign it a mesh IP (next available in 10.0.0.0/24):

3. Register the node with OmniMesh (run from any node already in the mesh):

omniwire_omnimesh(action="add-peer",
  id="newnode",
  public_key="<pubkey from step 1>",
  allowed_ips="10.0.0.N/32",
  endpoint="<public IP or DNS>:51820"
)

4. Push updated peer list to all nodes:

omniwire_omnimesh(action="sync-peers")

5. Bring the interface up on the new node:

wg-quick up wg0
ping 10.0.0.1   # verify hub reachability

Configure OmniWire on the New Node

Add the node to ~/.omniwire/mesh.json (create if absent):

{
  "nodes": [
    { "id": "node-a",   "host": "10.0.0.1", "user": "root", "identityFile": "~/.ssh/id_omniwire", "role": "storage" },
    { "id": "hostinger", "host": "10.0.0.2", "user": "root", "identityFile": "~/.ssh/id_omniwire", "role": "compute" },
    { "id": "windows",   "host": "10.0.0.3", "user": "Admin", "identityFile": "~/.ssh/id_omniwire", "role": "local" },
    { "id": "thinkpad",  "host": "10.0.0.4", "user": "user",  "identityFile": "~/.ssh/id_omniwire", "role": "local" }
  ]
}

Verify connectivity:

omniwire_mesh_status    # should show all nodes green
omniwire_doctor         # checks SSH, disk, mem, WireGuard, CyberBase

Connect Claude Code via MCP

Add to ~/.claude/claude_desktop_config.json (or your IDE's MCP config):

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

Restart Claude Code. Verify in a new session:

omniwire_mesh_status()   # 88 tools should be available

Environment Variables

Set persistently on a node. Values are written to /etc/environment, but tool responses only confirm whether a value is set and never echo the secret back:

omniwire_env(action="set", key="OP_SERVICE_ACCOUNT_TOKEN", value="<token>", node="node-a")
omniwire_env(action="get", key="OP_SERVICE_ACCOUNT_TOKEN", node="node-a")  # OP_SERVICE_ACCOUNT_TOKEN=<redacted: set>

CyberSync Auto-Distribution

CyberSync pushes configs, secrets, and memories to all nodes automatically via PostgreSQL.

# Check what's tracked
omniwire_coc(action="cybersync-status")

# Force push current config to all nodes
omniwire_coc(action="force-sync")

# Diff local state vs database
cybersync_diff()

On first run, CyberSync pulls node configs, 2FA seeds, and Claude memories from CyberBase — no manual copy-paste between machines.

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.0.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 88 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 (88 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

Changelog