FR: First-class Linux support (Rust rewrite) — optimize for cheap scalable Linux nodes

[chaodu-agent]

Summary

Add first-class Linux support for instance-mcp. Linux should be treated as a first-class citizen (arguably the primary target): cheap Linux mini PCs / VMs are easy to acquire and scale horizontally, whereas Mac minis are expensive and fewer. We should optimize for Linux deployment.

Motivation

• Scale-out: spin up many inexpensive Linux nodes (mini PCs, VMs, Raspberry Pi) as instance-mcp endpoints.
• Cost: Mac mini is expensive; Linux boxes are cheap and disposable.
• Deployment: prefer a single static binary, trivial cross-compile (x86_64 + arm64), minimal/no runtime deps, container/VM friendly.

Proposed approach: rewrite the Linux target in Rust

Rationale (Linux-first strategy):

• Deployment: single static binary, scp-and-run, zero runtime deps; small container images (distroless/scratch).
• Cross-compile: cargo + cross gives clean x86_64 and arm64 builds.
• Linux systems ecosystem: mature crates for the platform-specific bits — uinput (evdev/input-linux), Wayland (wayland-rs/smithay), /proc (sysinfo), HTTP (axum/hyper), JSON-RPC (serde_json). MCP has Rust references.
• Long term, Rust can also target macOS (objc2/FFI for CGEvent), giving a path to unify both platforms on one codebase.

Tradeoff acknowledged: this means rewriting ~3,073 lines and, in the interim, maintaining two codebases (macOS Swift + Linux Rust) with behavior kept in sync. Justified because Linux is the strategic primary target.

Current macOS implementation analysis (Swift)

• ~3,073 lines, Swift package, platforms: .macOS(.v14). Linked frameworks: ScreenCaptureKit, CoreGraphics, Network.
• Platform-agnostic (~62%) — pure Foundation, portable in spirit: MCPServer, MCPHTTPEndpoint, JSONRPC, HTTP, AuthPolicy, ToolProfile, UpstreamMCP, ReverseAttachClient, AttachManager, ExecTool, AsyncExecTools, ExecSupport, JobRegistry.
• Platform-specific (~640 lines, 5 files) needing Linux backends:
  • MouseTool / KeyTool / Input — CGEvent x27 -> Linux: uinput (ydotool or /dev/uinput)
  • ScreenshotTool — ScreenCaptureKit/CGImage -> Linux Wayland: grim
  • SysInfoTool — CGDisplay/sysctl/TCC -> /proc + wlr-randr; permission model differs
  • OsascriptTool — AppleScript -> drop on Linux (no equivalent)
  • Network.framework transport -> SwiftNIO/axum/hyper

Target environment verified (rpi1, Raspberry Pi 5)

• arch: aarch64; OS: Debian 13 (trixie); 4 cores, 8 GB.
• Display: labwc (Wayland) + lightdm. (SSH session is tty.)
• Screenshot tooling already present: grim, wlr-randr, scrot.
• /dev/uinput exists (root-only; needs a udev rule for non-root access).
• ydotool/xdotool: not installed. Swift: not installed. gcc/make present; docker/podman: no.
  Implication: most platform-specific features can shell out to existing CLIs (grim for screenshots, ydotool for input), which reduces the need for deep language bindings and de-risks the rewrite.

Scope / phased plan (proposal)

1. Rust MCP skeleton: HTTP transport + JSON-RPC + initialize + tool dispatch (axum + serde_json).
2. sys_info (read /proc, /sys, wlr-randr) — no side effects.
3. screenshot via grim (Wayland) with scrot fallback.
4. exec / async exec / job registry parity.
5. Input synthesis (mouse/key) via ydotool + /dev/uinput (udev permission rule).
6. Auth policy + reverse-attach parity.
7. arm64 + x86_64 CI, static binary packaging.

Effort estimate (rpi1-specific)

• Rust MCP PoC (handshake + sys_info + screenshot via grim): ~0.5–1 day.
• Minimal usable (headless: exec + sys_info + screenshot + MCP proxy): ~3–5 days.
• • input synthesis (ydotool/uinput + udev): +2–3 days.
• Full parity + tests + multi-arch CI: ~2 weeks.

Open questions

• Confirm Rust (this proposal) vs Swift-for-Linux (reuse ~62% but weaker Linux ecosystem, heavier deploy).
• Headless vs GUI scope per node type.
• Whether to eventually unify macOS onto the Rust codebase.

Architecture

Layered design: a platform-agnostic MCP core (transport, JSON-RPC, dispatch, auth, exec, jobs) with a thin platform backend behind a trait/protocol. macOS uses CoreGraphics/ScreenCaptureKit; Linux shells out to grim/ydotool and reads /proc.

flowchart TB
  subgraph client["openab-pty agent (MCP client)"]
    A[MCP over HTTP + JSON-RPC]
  end

  subgraph core["Platform-agnostic core (~62% reusable logic)"]
    T[HTTP/1.1 transport]
    J[JSON-RPC / MCP dispatch]
    AU[Auth policy + reverse-attach]
    EX[exec / async-exec / job registry]
    UP[upstream MCP proxy]
    PB{{PlatformBackend abstraction}}
  end

  subgraph macos["macOS backend (Swift, existing)"]
    M1[Input: CGEvent]
    M2[Screenshot: ScreenCaptureKit]
    M3[SysInfo: CGDisplay / sysctl / TCC]
    M4[osascript: AppleScript]
  end

  subgraph linux["Linux backend (Rust, target)"]
    L1[Input: ydotool / dev-uinput]
    L2[Screenshot: grim on Wayland]
    L3[SysInfo: /proc, /sys, wlr-randr]
    L4[osascript dropped]
  end

  A -->|HTTP| T --> J --> PB
  J --- AU
  J --- EX
  J --- UP
  PB -.selected at build time.-> macos
  PB -.selected at build time.-> linux

  linux --> N1[cheap x86_64 mini PC / VM]
  linux --> N2[arm64 Raspberry Pi 5]

Loading

Deployment target: single static binary per arch (x86_64 + arm64), scp-and-run, minimal deps.

Strategy / Roadmap (decided)

Pragmatic middle path — build Rust Linux first, designed cross-platform from day one, then grow into a single unified Rust codebase; keep Swift alive only as a transitional macOS backend until the Rust macOS backend is mature.

1. Phase 1 — Rust Linux, cross-platform by design. Write the Rust MCP core (transport, JSON-RPC, dispatch, auth, exec, jobs) plus a solid Linux backend. From the start, put all platform-specific behavior behind a PlatformBackend trait selected via #[cfg(target_os)], so the core never assumes an OS.
2. Phase 2 — add the macOS backend (FFI). Implement the macOS PlatformBackend in the same Rust codebase using objc2 / core-graphics FFI (CGEvent for input, ScreenCaptureKit for capture, sysctl/TCC for sysinfo). This evolves naturally into a single unified Rust codebase (route 2).
3. Phase 3 — retire Swift. The existing Swift macOS implementation keeps serving in production during Phase 1–2. Once the Rust macOS backend reaches parity and is validated, retire the Swift version.

Why this path:

• Avoids throwing away the working Swift build up front.
• Avoids the permanent two-codebase sync trap — there is one Rust core; only the thin platform backend forks by #[cfg].
• Linux-first (the strategic primary target) ships soonest; macOS converges later without a rewrite of the core.

flowchart TB
  subgraph client["openab-pty agent (MCP client)"]
    A[MCP over HTTP + JSON-RPC]
  end

  subgraph rustcore["Single Rust codebase"]
    T[HTTP transport]
    J[JSON-RPC / MCP dispatch]
    AU[Auth policy + reverse-attach]
    EX[exec / async-exec / job registry]
    UP[upstream MCP proxy]
    PB{{PlatformBackend trait -cfg target_os-}}
  end

  subgraph linux["Linux backend -Phase 1, Rust-"]
    L1[Input: ydotool / dev-uinput]
    L2[Screenshot: grim on Wayland]
    L3[SysInfo: /proc, /sys, wlr-randr]
  end

  subgraph macrust["macOS backend -Phase 2, Rust FFI-"]
    R1[Input: core-graphics CGEvent]
    R2[Screenshot: objc2 ScreenCaptureKit]
    R3[SysInfo: sysctl / TCC]
  end

  subgraph swift["Swift macOS -existing, transitional-"]
    S1[serves until Rust macOS parity, then retired]
  end

  A -->|HTTP| T --> J --> PB
  J --- AU
  J --- EX
  J --- UP
  PB -.cfg linux.-> linux
  PB -.cfg macos, Phase 2.-> macrust
  swift -.replaced by.-> macrust

  linux --> N1[cheap x86_64 mini PC / VM]
  linux --> N2[arm64 Raspberry Pi 5]

Loading

[chaodu-agent]

Next steps — ADR merged, Phase 0 gates opened

The ADR is merged to main (docs/adr/linux-rust-port.md), Status Proposed, independently reviewed (fable + sol, both APPROVE after revision).

Per the ADR's phase gates, the plan does not commit to the full Rust buildout until the Phase 0 de-risk spikes pass. Tracking issues (each with explicit exit-criteria):

• Phase 0a: macOS FFI spike (objc2/ScreenCaptureKit/CGEvent + signed+notarized CI build) #22 — Phase 0a: macOS FFI spike (objc2/ScreenCaptureKit/CGEvent + signed+notarized CI build). Kill condition → fall back to thin-host. Decide before Phase 1.
• Phase 0b: headless/seat spike — screenshot+input on a compositor-less Linux VM #23 — Phase 0b: headless/seat spike (screenshot+input on a compositor-less Linux VM, or declare a graphical-seat-required contract).
• MCP + reverse-attach conformance/differential test suite (Phase 1 deliverable) #24 — MCP + reverse-attach conformance/differential suite (Phase 1 deliverable; the anti-drift + security-parity contract; defines parity).

Recommended order: start with #23 (validates the scale-on-cheap-Linux premise cheaply on real hardware) and #24 (contract can be authored against the existing Swift oracle now); #22 needs macOS signing identity + CI. Phase 1 (Rust core + Linux backend, rustls) begins only after #22/#23 resolve; ADR → Accepted after the Validation gate (incl. auth/reverse-attach via #24) passes.

[chaodu-agent]

Phase 1 PoC — Rust instance-mcp running on rpi1 (aarch64 Debian 13) ✅

Built and ran a minimal Rust MCP-over-HTTP server on rpi1 (Raspberry Pi 5, aarch64, Debian 13 trixie). This exercises ADR Validation gate (a)+(b) on real hardware.

Result — all MCP methods verified over HTTP

• initialize → serverInfo {instance-mcp-poc 0.1.0}, protocolVersion, capabilities.
• tools/list → sys_info, screenshot (with input schemas).
• tools/call sys_info → real data: arch=aarch64, cpu_cores=4, memory_gb=7.87, os="Debian GNU/Linux 13 (trixie)", host=rpi1, uptime, and displays via wlr-randr.
• tools/call screenshot → grim produced a real PNG 2,065,713 bytes. (Note: rpi1's labwc was on a headless output NOOP-1 at the time; grim still captured — consistent with Phase 0b: headless/seat spike — screenshot+input on a compositor-less Linux VM #23's software-render finding.)

Confirms the ADR's minimal-deps / self-contained thesis

• std-only HTTP/1.1 + serde_json — no tokio/hyper for the PoC.
• 5 small crates, 725 KB single binary, 10.5s native release build on the Pi.
• sys_info reads /proc + /etc/os-release + wlr-randr; screenshot shells out to grim (per the Phase 0b: headless/seat spike — screenshot+input on a compositor-less Linux VM #23 wlroots toolchain).

Scope / not yet done (this is a PoC, not Phase 1 complete)

• No auth / reverse-attach yet (the highest-risk surface — gated behind MCP + reverse-attach conformance/differential test suite (Phase 1 deliverable) #24 conformance suite before real auth code).
• Input tool (wlrctl) not wired into this PoC binary yet (verified separately in Phase 0b: headless/seat spike — screenshot+input on a compositor-less Linux VM #23).
• Hand-written HTTP is PoC-grade; Phase 1 proper will choose the real transport (rustls, etc. per ADR).

Crate lives at ~/repo/instance-mcp-poc on rpi1. This de-risks the Rust-on-Linux core: the MCP surface + sysinfo + screenshot all work on aarch64 with a tiny dependency footprint. Next real steps remain #24 (conformance/auth) and #22 (macOS FFI) per the phase gates.

[chaodu-agent]

PoC now AUTH-GATED on rpi1 — 9/9 paths verified

Wired the conformance-proven AuthPolicy (from #24) into the rpi1 PoC binary (v0.2.0). /mcp is now gated on AuthPolicy.decide() — the same logic that passed 16/16 conformance vectors, now enforced at the HTTP transport.

Config (env)

• MCP_TOKEN — bearer token
• MCP_ALLOW_LOGIN — comma list of allowed Tailscale-User-Login
• MCP_INSECURE_LOCAL=1 — allow loopback-only unauthenticated (debug)
• Startup validate() refuses to boot with none set.

Verified on rpi1 (curl, 9/9)

#	scenario	expect	got
1	no auth env	refuse start	✅ FATAL/exit
2	token set, no Authorization	401	✅
3	token set, wrong token	401	✅
4	token set, right token	200 + serverInfo	✅
5	allow-login, matching login	200	✅
6	allow-login, wrong login	401	✅
7	allow-login, no identity	401	✅
8	insecure-local, loopback no headers	200	✅
9	insecure-local + spoofed X-Forwarded-For	401	✅

Deny returns HTTP 401 + JSON-RPC error {code:-32001, message:"unauthorized: <reason>"}; allow proceeds to MCP dispatch. Build: 1.38s, 733 KB, still std + serde_json only.

Where we are

rpi1 now runs a minimal but auth-gated instance-mcp: MCP handshake + sys_info + screenshot (grim) + bearer/login/insecure-local auth matching the Swift semantics. This is the Linux core with a real security boundary — no longer an open endpoint.

Still pending (per phase gates)

• reverse-attach WS layer (dial-out, verifier handshake, close codes, redial) — the differential in MCP + reverse-attach conformance/differential test suite (Phase 1 deliverable) #24.
• per-connection tool profiles (owner vs sandbox).
• Phase 1 proper transport (rustls) replacing the hand-written HTTP.
• Phase 0a: macOS FFI spike (objc2/ScreenCaptureKit/CGEvent + signed+notarized CI build) #22 macOS FFI (needs signing identity).

Binary at ~/repo/instance-mcp-poc on rpi1.

[jinwei-pikmin]

A Linux (Ubuntu/GNOME) Rust port, verified against a real openab-pty runtime

Thanks for the ADR and the Phase 0 work — I followed its shape (one core, PlatformBackend trait, rustls) and built a Linux port on an x86_64 Ubuntu 26.04 / GNOME 50 Wayland laptop. Branch: https://github.com/jinwei-pikmin/instance-mcp/tree/linux-rust-port (rust/). Sharing it as input to #15/#23/#24, not as a finished PR.

What it covers (same flags, auth table and wire contract as the Swift build)

• MCP Streamable HTTP + sessions; AuthPolicy (login AND bearer, constant-time, insecure-local); sys_info; exec + exec_start/poll/list/cancel.
• Reverse attach: POST/GET/DELETE /attach, owner/sandbox profiles, mint via admin_credential with ttl_secs (0.6.4 parity), close-code policy + backoff. Verified end to end against a real openab-pty runtime (post-#38): attached to a k8s pod session, stayed attached through the 20 s ping window, sandbox tools/list without exec*, a coding CLI in the pod driving the laptop through $OPENAB_TOOLS_MCP_URL.
• screenshot / mouse / key on GNOME via xdg-desktop-portal (Screenshot + RemoteDesktop with persist_mode=2) — relevant to the ADR's open question on non-wlroots desktops, since grim/wlrctl don't work on Mutter.

Findings that may matter for the ADR

• GNOME fractional scaling: the portal bounds-checks absolute pointer motion in logical stream size while Mutter reads it in physical pixels, so only the top-left 1/scale is reachable absolutely; I move absolutely as far as allowed and finish with relative motion.
• Remote key input drops keysyms not in the active keymap (CJK, accents); non-ASCII goes through IBus/GTK ctrl+shift+u entry.
• OpenAB Connect (1.0.18) decodes the Swift sys_info shape: with displays: [] it stops polling screenshots; whole numbers should be encoded as ints like the Swift encoder.

Bugs found in review that also exist in the Swift build (happy to send small Swift PRs):

1. exec waits for pipe EOF with no bound, so exec "app &" hangs until the app exits (and aborting the readers instead kills the background app with SIGPIPE — keep draining).
2. Reverse-attach backoff never resets after a successful attach (stays at 30 s for the rest of the grant).
3. exec_poll reads the whole log with no per-poll cap (can exceed the 16 MiB attach frame).

54 unit tests, clippy clean. I haven't run the #24 vectors yet since they're not in the repo — if you publish auth_vectors.json / the disposition vectors I'll run them against this port. How would you like this integrated — split PRs (core / reverse-attach / portal backend), or kept as a reference for Phase 1?