Skip to content

feat(fleet): manage remote Muxa hosts over SSH - #77

Merged
jiunbae merged 6 commits into
mainfrom
feat/fleet-remote-hosts
Aug 20, 2026
Merged

feat(fleet): manage remote Muxa hosts over SSH#77
jiunbae merged 6 commits into
mainfrom
feat/fleet-remote-hosts

Conversation

@jiunbae

@jiunbae jiunbae commented Aug 20, 2026

Copy link
Copy Markdown
Member

Summary

Add a production-oriented physical-host Fleet layer to Muxa:

  • model host -> session -> window -> pane(agent) with persistent UUID NodeIds
  • always publish the controller itself as the first-class local host
  • manage Kubernetes-style labels, annotations, selectors, and compact/wide/JSON host views
  • connect remote nodes through persistent OpenSSH stdio relays with observe/control policy
  • expose Fleet operations through CLI, TUI, local IPC, dashboard API, and MCP
  • preserve per-host last-known state and explicit lifecycle/error states
  • delegate the single-local-host path to the mature native muxa watch
  • document deployment, security, performance, protocol, and operations in English and Korean

This branch contains six logical commits because the local main branch was already one commit ahead of origin/main:

  1. 5ea744e adds natural @peer MCP collaboration routing
  2. 9c24f8e adds the physical-host Fleet implementation
  3. 38f1fba updates h2 for RUSTSEC-2026-0258
  4. 7bd8c1b exposes the controller as the always-present local Fleet host
  5. b85d426 integrates native watch, compact tables, rich multi-host UI, and push invalidation
  6. 964a348 hardens selector subscriptions, navigation, parent messaging, and rendering safety

Local controller node

  • available without Fleet configuration and with fleet.enabled = false
  • always sorted first as alias local through an in-process adapter
  • carries stable NodeId plus immutable local/transport and Kubernetes platform labels
  • accepts user labels and annotations through muxa host label local and muxa host annotate local
  • supports the same selectors, topology, captures, prompts, attach, dashboard, and MCP surfaces
  • cannot be added, removed, disabled, or disconnected
  • verifies exact pane keys and rejects a duplicate local NodeId through SSH

Status and watch UX

  • terminal-width-aware HOST/STATE/MODE/AGENTS/PANES/ATTN/AGE default status table
  • -L, --show-labels, -o wide, and -o json progressively expose richer inventory
  • local-only selection delegates to native watch with its complete feature set
  • multi-host tree/swarm layouts with host/session/window/pane inspectors and window geometry mosaics
  • Arrow Up/Down visits structural rows; j/k jumps directly between actionable panes
  • focus/manual/always expansion follows configured view depth without forcing singleton traversal
  • Swarm always keeps its visible agent and actual action target synchronized
  • m works from a session, window, or pane; parents choose the lowest-index live agent pane
  • the shared / message-skill palette works in the multi-host composer
  • --include-paneless exposes detached agents, including search and attention filtering, while pane-only actions remain disabled

Architecture, performance, and safety

  • no inbound Fleet listener and no SSH port forwarding
  • OpenSSH BatchMode stdio transport with protocol/capability negotiation
  • observe is the remote default; prompts require explicit control permission
  • exact host/backend/session/window/pane identities prevent cross-host collisions
  • bounded frames, lines, stderr, pending commands, prompts, and capture payloads
  • controller-side terminal sanitization, including remote identifiers and mosaic titles
  • no automatic retry for mutating prompt sends
  • isolated per-host tasks/caches, bounded connection concurrency, backoff, jitter, keepalive, and command deadlines
  • revision-aware snapshots preserve newer state transitions during slow refreshes
  • selected-window captures are lazy, rate-limited, and serialized to avoid stale pending races
  • selector-scoped fleet_subscribe installs its receiver before ACK; the client fetches a fresh snapshot after ACK
  • invalidations coalesce for 75 ms, refresh at most four times per second, and explicitly resync after stream lag
  • modern daemons retain a 15-second reconciliation poll; older daemons fall back to one-second polling

User surfaces

  • muxa host add|list|show|remove|label|tag|annotate|enable|disable|doctor
  • muxa fleet status|watch|connect|disconnect|refresh|panes|capture|send|attach
  • muxa watch --fleet --selector ...
  • Fleet dashboard read and PAT-protected command endpoints
  • muxa_fleet_status, muxa_fleet_capture, and muxa_fleet_send_prompt MCP tools
  • docs/FLEET.md and docs/FLEET.ko.md

Validation

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets --locked -- -D warnings
  • cargo test --workspace --locked
  • muxa core: 643 passed, 1 environment-dependent rmux smoke test ignored
  • sink integration: 7 passed
  • muxa CLI: 675 passed, plus 12 e2e tests
  • muxad: 58 passed
  • selector stream filtering plus enter/leave membership round trip
  • focus/manual/view navigation, Swarm selection, parent message routing, paneless search, and sanitization regressions
  • git diff --check

Relationship to #65

PR #65 manages agent work inside a local Muxa environment. This PR manages physical nodes and their multiplexer hierarchy. They are complementary; ordinary README/CLI conflict resolution may be needed if #65 lands first.

Rollout

The controller works immediately as local. Controller and remotes should run the same Fleet-capable Muxa version. Start remotes in observe mode, verify muxa host doctor, then grant control only where remote prompt dispatch is needed. Cut a release after review and merge.

@jiunbae
jiunbae marked this pull request as ready for review August 20, 2026 11:07
@jiunbae
jiunbae merged commit d0f1ff0 into main Aug 20, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant