Operational Tooling for a Multi-Machine Coding-Agent Fleet

Overview

A set of small, dependency-free operational tools that keep a three-Mac fleet of coding-agent environments (orchestrated through T3 Code, driven over MCP) paired, reachable and auditable. The pieces cover device-pairing lifetime and expiry alerts, long-lived token issuance and distribution between machines, remote file and thread RPC helpers, and a read-only security triage runbook with snapshot diffing.

Why It Exists

Running agents across several machines means several moving parts that silently break: the orchestrator hard-codes a 30-day lifetime on every device pairing with no renewal, so phones, tablets and desktop environments drop off after a month; cross-machine MCP tokens have to be re-issued and distributed without ever being pasted into chat; and a suspected hostile event on a hosted product called for a repeatable way to check every host for persistence, listeners and remote-access exposure. Each tool here closes one of those gaps with the smallest possible footprint (plain Node or shell, launchd, no packages).

What We Built

• t3-pair-proxy (pair-proxy.mjs, install.sh): a transparent HTTP + WebSocket proxy that sits in front of the local orchestrator server on a fixed port. It forwards everything unchanged except the pairing-redemption POST /oauth/token: after the real server validates the one-time credential, the proxy issues a 10-year session with identical scopes through the bundled CLI, swaps it into the response and revokes the 30-day one. WebSocket upgrades are spliced at the raw TCP level after replaying the request head; the upstream port is re-read from the runtime file on every request because it can change between app launches. Installed as a RunAtLoad + KeepAlive launchd agent with a post-install health probe.
• t3-pair-watch (watch.mjs, install.sh): a daily launchd job on every machine that reads device sessions straight from the orchestrator’s SQLite state (read-only, filtering out CLI and bot sessions), classifies them into expiry stages (3 days left, 1 day left, expired within a grace window), skips stale or already-replaced pairings, mints a single-use 2-day re-pair link per affected device via the CLI (revoking yesterday’s), and writes a local JSON report. In --notify mode one designated machine collects the peers’ reports over the orchestrator’s projects.readFile RPC and sends one message per new stage, with the bare link in its own message for one-tap copying. Delivery is iMessage via osascript with automatic fallback to a local WhatsApp bridge; --dry-run mints and sends nothing and masks tokens in output.
• t3-maintenance (bundle/, pair-proxy/): the helper bundle that is pushed to each machine’s maintenance project through the orchestrator’s projects.writeFile RPC (the only path that API allows writes to). It includes refresh-tokens.mjs (issue three 10-year scoped MCP tokens per machine, install the local one with 0600 permissions, stage the others in an outbox, revoke old sessions only after verification), pair.mjs (pair an MCP client with narrow orchestration:read/operate scopes and verify the granted scope, never printing tokens), tunnel.mjs (an HTTP CONNECT forwarder for machines running userspace Tailscale, where Node’s WebSocket ignores proxy variables), remote-file.mjs, v2.mjs (launch/send/read agent threads over orchestration protocol 2), mcp-call.mjs (invoke a single MCP tool in a fresh process) and an idempotent patch-t3client.mjs that adds the protocol-2 header and WebSocket parameter to the shared client.
• security-enforcement (scripts/mac-triage.sh, scripts/monitor.sh, reports/): a read-only macOS triage script that snapshots accounts, admin group, logins, FileVault/SIP/Gatekeeper/firewall state, SMB shares, listening and external TCP connections, DNS and proxy, /etc/hosts, SSH keys, LaunchAgents/Daemons, privileged helpers, background and login items, cron, profiles, sudoers, suspicious shell-rc lines, processes from unusual paths, recently modified executables, system extensions and recent ssh / screen-sharing auth from the unified log, each guarded by a hard timeout. monitor.sh runs it locally or streams it over ssh, stores the report, and diffs only the stable sections against the previous snapshot. The README records the baseline findings, the exposure to reduce (firewall off, multiple remote-control paths, guest-writable shares, Docker databases bound to all interfaces) and an ordered, no-downtime hardening plan.
• cswap-ops: reserved for account rotation across agent CLIs; at the time of writing the repository holds only its README title and no code.

Technologies & Approach

Everything is plain Node 22 ESM using only core modules (http, net, child_process, fs) or Bash/Zsh, so the tools run on a fresh Mac with nothing installed beyond the orchestrator app. Long-running pieces are launchd agents written by their own install.sh (node discovery, log paths, calendar or keep-alive scheduling, uninstall). Privileged operations go through the orchestrator’s bundled CLI (auth session issue/revoke, auth pairing create/revoke) rather than touching its database for writes; reads use sqlite3 -readonly. Cross-machine work uses the orchestrator’s own RPC (projects.readFile/writeFile, orchestration.launchThread) over Tailscale, with a CONNECT tunnel for the userspace-networking case. Secrets are handled by convention throughout: config and credential files are created 0700/0600, tokens are never logged, dry-run output masks them, and the security scripts change nothing on the host.

Outcome / Impact

Device pairings created through the proxy now last for years instead of a month, and any remaining short-lived pairings produce a timed reminder with a ready-to-use link rather than a surprise disconnect. MCP tokens between the machines can be rotated and distributed from one place without manual copying. The triage scripts gave a documented baseline for all hosts after the incident, with a daily diff that surfaces only meaningful changes, and a concrete hardening checklist derived from what was actually found.

Capabilities Demonstrated

• Transparent HTTP/WebSocket proxying in zero-dependency Node, including raw TCP upgrade splicing
• Extending a third-party tool’s auth lifecycle without patching it (token swap at the redemption boundary)
• launchd-based scheduling and keep-alive daemons with self-contained installers
• Cross-machine automation over an orchestrator’s RPC and MCP interfaces, tunnelled through Tailscale
• Scoped, file-permission-safe token issuance, distribution and revocation
• Read-only macOS security triage with timeout guards and stable-section snapshot diffing
• Operational runbooks that record baseline, exposure and ordered remediation