Smolmux Gdb MCP server

smolmux

A portable C11 device multiplexer. Holds a device connection open (serial UART, GDB stub) and multiplexes access to multiple clients over Unix sockets using newline-delimited JSON.

Single static binary, low latency, small footprint - built for daily serial and GDB bring-up on Linux.

New here? docs/START-HERE.md is a one-screen router - find your intent (run it, bring up a new board with an AI agent, understand the architecture, hack on the code) and it points you to the right doc.

Example: probe an unknown board

One broker holds SWD; smolmux-gdb-mcp runs probeunknownboard. On a SAM C21 Xplained Pro that path decoded Cortex-M0+ from CPUID, named the part via SAM DSU DID, rejected a false STM32 match, and wrote a starter *.gdb-profile.json. Tools, register values, and profile shape: docs/demo-samc21-probe-transcript.md.

Day-to-day serial (multi-client, U-Boot break-in, flasher handoff): docs/daily-driver.md.

Features

(the I/O log records everything sent to and from the device, including anything typed at a login prompt — it is created 0600 under your private state directory, and smolmux refuses to write it through a symlink or to a file owned by another user)

• Serial UART, GDB MI, and serial-over-TCP (telnet + RFC2217) device links via vtable polymorphism
• Multiple concurrent clients over Unix sockets with role-based access (observer/controller/takeover)
• Expect engine - concurrent regex matching on the device byte stream with timeouts
• Anomaly detection - pattern-based crash/error detection with cooldown and incident tracking
• Output history - timestamped ring buffer for replay by late-joining clients
• Structured logging - JSONL I/O log + human-readable text log with rotation

The wire protocol is cleartext, and any client that completes the handshake gets full control of the device — console writes, pins, BREAK, SysRq, GDB. On loopback without --auth-token, the broker generates a token into a 0600 file in $XDGRUNTIMEDIR (or /tmp), so other local users and processes cannot connect; your own smolmux-monitor / smolmux-mcp read it automatically, and smolmux-cli token prints it. For remote use, keep the bind on loopback and reach it over an SSH tunnel or WireGuard rather than exposing the port; smolmux refuses to serve a non-loopback TCP bind with no --auth-token. --insecure-no-auth turns both protections off.

• Network sinks - TCP and WebSocket for remote access (loopback by default).

• MCP servers - standalone smolmux-mcp / smolmux-gdb-mcp attach to a running broker; optional in-process --mcp sink for single-process stdio
• Boot tracking & autoresponder - ordered boot stages, stall events, standing expect->send rules
• Autoboot interrupt - broker-side key flood (and optional DTR/RTS reset) for bootdelay=0 U-Boot
• Device profiles / board manifests - JSON configs for prompts, anomalies, multi-wire boards
• Auto-reconnect - exponential backoff recovery on USB-serial disconnect
• Build-time feature selection - Kconfig-based; UART-only builds carry no GDB/TCP/WebSocket code

Quick start

cmake -B build && cmake --build build -j$(nproc)
./build/smolmux /dev/ttyUSB0

Connect a client:

# Needs a running broker (above). Auto-discovers the socket from the port name.
./build/smolmux-monitor /dev/ttyUSB0

Day-to-day workflows (profiles, logs, U-Boot break-in, multi-wire boards): docs/daily-driver.md. Intent router: docs/START-HERE.md.

Build

cmake -B build && cmake --build build -j$(nproc)   # Default (all features)
ctest --test-dir build                               # Run tests

Feature profiles

Shortened. The full README is on GitHub.