zwire-host 0.3.1

███████╗██╗    ██╗██╗██████╗ ███████╗    ██╗  ██╗ ██████╗ ███████╗████████╗
╚══███╔╝██║    ██║██║██╔══██╗██╔════╝    ██║  ██║██╔═══██╗██╔════╝╚══██╔══╝
  ███╔╝ ██║ █╗ ██║██║██████╔╝█████╗█████╗███████║██║   ██║███████╗   ██║
 ███╔╝  ██║███╗██║██║██╔══██╗██╔══╝╚════╝██╔══██║██║   ██║╚════██║   ██║
███████╗╚███╔███╔╝██║██║  ██║███████╗    ██║  ██║╚██████╔╝███████║   ██║
╚══════╝ ╚══╝╚══╝ ╚═╝╚═╝  ╚═╝╚══════╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝

[UNIVERSAL LOCAL HOST // SYSINFO · FS · EXEC · PTY · KV · OS]

"One pipe. One binary. The whole machine — reachable from anywhere."

zwire-host is a single self-contained Rust binary (~500 KB, no Python, no psutil) that exposes the local machine to any app over one JSON message protocol. It began as the Chrome native-messaging host for zwire's HUD; it is now a universal local endpoint you can talk to from a browser extension and from tmux, emacs, desktop apps, plugins, shell scripts, and any language — because it also runs as a Unix-socket daemon speaking newline-delimited JSON, the one protocol every tool already has.

It streams live system stats (sysinfo), runs PTY terminals (portable-pty), crawls and watches/tails the filesystem, execs commands, runs background jobs that notify on completion, lists/kills processes, brokers a pub/sub event bus that federates across a mesh of peered hosts, keeps a per-app key/value store, and does clipboard / notify / open. Every capability is reachable over every transport, and the whole thing is also a Rust library so sibling hosts (e.g. zpwrchrome-host) can embed it.

zwire · zpwrchrome · strykelang

Table of Contents

• [0x00] Overview
• [0x01] Transports
• [0x02] Protocol / Commands
• [0x03] CLI
• [0x04] Library use (embed as a dependency)
• [0x05] Chrome install
• [0x06] Build · Cross-Platform · CI
• [0x07] License

[0x00] Overview

Extensions, editors, and plugins can't read the machine or spawn a shell. zwire-host does the privileged work once and hands it to everyone: a live statusbar (cpu / mem / net / battery / temp …), an embedded terminal, a filesystem crawler, a command runner, and a small state store. Shipping it as one static Rust binary means the consuming bundle has zero runtime dependencies — no system Python, no pip install psutil, nothing to break on a fresh machine.

[0x01] Transports

Both transports feed the same dispatcher, so every command below works over either one.

The daemon uses each platform's native local IPC — a Unix domain socket on macOS/Linux and a named pipe on Windows — so it runs everywhere your apps do:

• macOS / Linux — $ZWIRE_HOST_SOCK, else $XDG_RUNTIME_DIR/zwire-host.sock, else ~/.zwire/host.sock. Created 0600 under a 0700 dir — owner-only, since it exposes exec/fs/pty.
• Windows — $ZWIRE_HOST_SOCK, else the per-user pipe \\.\pipe\zwire-host-<user>. (--socket <name> overrides the pipe name.)

Requests may carry an id; it is echoed on the matching reply so a client can multiplex many in-flight requests, streams, and terminals over one connection.

[0x02] Protocol / Commands

Discovery & state

System stats

Filesystem (paths accept a leading ~)

File watching (streaming observers, keyed by id)

Exec & OS

Background jobs (long-running commands; run in the daemon, survive the connection)

Process tools

Pub/sub event bus (the host as a coordination hub across apps)

The daemon itself publishes on scheme / ui whenever those change, so a subscribed app (a HUD, an editor) gets live theme sync without polling.

Host-to-host peering (a mesh of daemons across machines)

Run daemons with TCP peering and the bus federates across machines — a publish (or a scheme/ui change) on one host reaches subscribers on every peer — and you can run a request on another host:

# machine A: listen for peers
zwire-host serve --tcp 0.0.0.0:7420 --token SECRET --name laptop
# machine B: listen, and dial A
zwire-host serve --tcp 0.0.0.0:7420 --token SECRET --name desktop --peer A.local:7420

Inbound TCP is gated by a shared --token (or $ZWIRE_HOST_TOKEN): a connection must auth / peer_hello with it before anything privileged. Local Unix-socket clients are trusted and never need it. Federation is single-hop (a forwarded event is delivered locally but not re-forwarded), which covers star and fully-meshed topologies without loops.

PTY terminals (multiplexed by id)

Legacy zwire scheme/ui (unchanged): {"cmd":"get"}, {"scheme":"matrix"}, {"ui":{…}} bridge ~/.zwire/hud-scheme + ~/.zwire/hud-ui.json.

[0x03] CLI

zwire-host serve &                                   # run the socket daemon
zwire-host call '{"cmd":"hostinfo"}'                 # one request, one reply
zwire-host call '{"cmd":"fs_walk","path":"~/src","ext":"rs"}'
echo '{"cmd":"exec","program":"git","args":["status"]}' | zwire-host call
zwire-host call --stream '{"cmd":"sysinfo_start"}'   # keep printing frames

From any tool that can write a line to the endpoint — no client library needed. zwire-host call is the portable path; or connect to the socket/pipe directly:

# macOS / Linux — raw Unix socket
printf '{"cmd":"sysinfo_once"}\n' | nc -U ~/.zwire/host.sock
# any platform — via the bundled client
zwire-host call '{"cmd":"sysinfo_once"}'

[0x04] Library use (embed as a dependency)

The crate is a library too (zwire_host), so sibling hosts can pull it in to crawl and exec without re-implementing anything:

[dependencies]
zwire-host = { git = "https://github.com/MenkeTechnologies/zwire-host" }

use zwire_host::api;

// crawl the filesystem
for e in api::walk("~/src", Some("rs")) {
    println!("{}", e.path.display());
}

// run a command, get bytes back
let out = api::exec("git", ["status", "--porcelain"]).unwrap();
println!("exit {:?}: {}", out.code, out.stdout_str());

Or drive the whole dispatcher yourself over any transport with zwire_host::{Peer, Session}, or just delegate main to zwire_host::run(std::env::args().skip(1).collect()).

[0x05] Chrome install

Point a native-messaging host manifest's path at the binary and list the allowed extension origins:

{ "name": "com.zwire.hud", "type": "stdio",
  "path": "/abs/path/to/zwire-host",
  "allowed_origins": ["chrome-extension://<id>/"] }

Drop it in the browser's NativeMessagingHosts/ directory (or the profile's). zwire's scripts/localinstall.sh builds this binary and wires the manifest automatically when packaging the .app.

[0x06] Build · Cross-Platform · CI

cargo build --release          # -> target/release/zwire-host (~500 KB)
cargo test                     # exercises the protocol over both transports

sysinfo and portable-pty abstract the OS, so the same source builds for macOS · Linux · Windows. Both transports work on all three: native messaging everywhere, and the serve/call daemon over Unix domain sockets on macOS/Linux and named pipes on Windows (via interprocess, a Windows-only dependency). Battery reporting is native on every platform: pmset on macOS, /sys/class/power_supply on Linux, and GetSystemPowerStatus on Windows — absent on machines with no battery (desktops, VMs), where the segment is omitted.

CI runs the four canonical polish gates on Ubuntu + macOS + Windows:

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
cargo doc --no-deps                        # RUSTDOCFLAGS=-D warnings
cargo test

[0x07] License

MIT © MenkeTechnologies