Skip to content

feat(cmuxd-remote): add TCP listener mode for Tailnet direct connections #201

@Jesssullivan

Description

@Jesssullivan

Summary

cmuxd-remote currently only supports serve --stdio (stdin/stdout JSON-RPC). This works well for SSH-piped sessions but requires an SSH tunnel for every connection. Adding a TCP/Unix socket listener mode would enable direct Tailnet connections without SSH overhead.

Motivation

In a fleet of 5+ hosts on a Tailscale mesh, each cmux LAB session currently:

  1. Opens an SSH connection to the remote
  2. The LAB app internally invokes cmuxd-remote serve --stdio over the pipe
  3. JSON-RPC flows over SSH

With a TCP listener mode, cmuxd-remote could bind directly to the Tailscale interface, eliminating the SSH tunnel entirely. This enables:

  • Lower latency (no SSH handshake/encryption overhead — Tailscale already encrypts via WireGuard)
  • Direct MagicDNS discovery (cmux connect honey.tailnet.ts.net:5555)
  • Service advertisement via Tailscale Serve or DNS SRV records
  • Relay token auth (CMUX_RELAY_TOKEN) for authentication instead of SSH keys

Proposed CLI

# Current (stdio only)
cmuxd-remote serve --stdio

# New: TCP listener
cmuxd-remote serve --tcp :5555
cmuxd-remote serve --tcp 100.113.89.12:5555  # Bind to Tailscale IP only

# New: Unix socket listener
cmuxd-remote serve --socket /tmp/cmuxd.sock

# Combined (local socket + TCP)
cmuxd-remote serve --tcp :5555 --socket ~/.local/state/cmux/cmux.sock

Auth

Use existing CMUX_RELAY_TOKEN challenge-response auth (already in the binary but only for relay mode). For TCP mode, require token auth on every new connection.

Integration with crush-dots

Once TCP mode exists, the crush-dots Nix flake can:

  • Add systemd/launchd service definitions (persistent daemon, not on-demand)
  • Bind to Tailscale IP via tailscale ip -4 at service start
  • Generate cmux.json with direct cmux://honey.tailnet.ts.net:5555 URIs
  • Use Tailnet ACL tags (tag:cmuxd-fleet) for service discovery

Context

  • cmuxd-remote 0.75.0 deployed across 4 fleet hosts (honey, yoga, xoxd-bates, neo)
  • JSON-RPC ping verified over SSH on all hosts
  • Phase 5 (SSH-piped availability) complete
  • Phase 6 (Tailnet direct) blocked on this feature

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions