Hub Setup

The hub is a coordinator that manages multiple muxd daemon instances (nodes) across machines. It tracks registered nodes, proxies requests between them, aggregates logs, and lets you switch between nodes from a single TUI.

There are two roles:

• Hub — the coordinator process (muxd --hub). Runs on one machine.
• Node — any muxd daemon that registers with the hub. Runs on one or more machines.

A remote TUI connects to the hub, picks a node, and all traffic is proxied through.

Quick start

1. Start the hub

muxd --hub runs in the foreground and blocks your terminal. On a remote machine, install it as a service:

# Create config — hub only needs its own settings
mkdir -p ~/.config/muxd
cat > ~/.config/muxd/config.json << 'EOF'
{
  "hub_bind_address": "0.0.0.0"
}
EOF
chmod 600 ~/.config/muxd/config.json

# Install and start the hub service
muxd -service install-hub
systemctl --user start muxd-hub
systemctl --user enable muxd-hub

Enable lingering so the service runs without an active SSH session:

loginctl enable-linger

2. Get the hub token

The hub generates a bearer token on first start. Retrieve it with:

muxd --hub-info

This prints the token, address, and a QR code. You'll need this token for both registering nodes and connecting a TUI.

3. Register a node

On each machine running a muxd daemon, configure it to register with the hub. These settings are in the node config group (/config node):

/config set hub.url http://<hub-host>:4097
/config set hub.node_token <hub-token>
/config set hub.node_name my-server

Then start (or restart) muxd:

muxd --daemon              # headless daemon mode
muxd --bind 0.0.0.0        # TUI mode (also registers with hub)

Both modes register with the hub and send heartbeats every 30 seconds. You'll see hub: registered as client <id> in the output.

If the hub and daemon run on the same machine, they share the same ~/.config/muxd/config.json. The hub only reads hub.* keys. The daemon reads hub.url/hub.client_* keys along with its own model/provider/API key settings. The hub does not share or distribute config to clients — each client manages its own API keys and model settings locally.

4. Open the firewall

The hub listens on port 4097 (separate from the daemon port 4096).

Fedora / RHEL (firewalld):

sudo firewall-cmd --add-port=4097/tcp --permanent && sudo firewall-cmd --reload

Ubuntu / Debian (ufw):

sudo ufw allow 4097/tcp

5. Connect a TUI to the hub

From any machine with muxd installed:

muxd --remote <hub-host>:4097 --token <hub-token>

The TUI connects to the hub and presents a node picker. Select a node to start or resume a session on that machine. All traffic — including /config commands — is proxied through the hub to the selected node.

Running the hub locally

For testing or local use, you can run the hub in the foreground:

muxd --hub                        # localhost only
muxd --hub --hub-bind 0.0.0.0     # all interfaces

This blocks the terminal. Press Ctrl+C to stop.

How it works

The hub runs on port 4097 and provides:

• Node registry — nodes register on startup and send heartbeats every 30 seconds. The hub marks a node offline after 90 seconds of inactivity.
• Request proxy — session and agent traffic is routed through the hub to the target node. The hub swaps its own auth token for the node's daemon token transparently.
• Log broker — nodes push log entries to the hub. The hub stores them and streams them to SSE subscribers for centralized monitoring.
• Session aggregation — the hub queries all online nodes and returns sessions grouped by node for cross-node discovery.
• Shared memory — nodes push project memory facts to the hub and pull new facts every 60 seconds. A fact saved on one node appears on all other nodes automatically.

Service management

All hub service commands:

muxd -service install-hub         # install hub service
muxd -service uninstall-hub       # remove hub service
muxd -service start-hub           # start hub service
muxd -service stop-hub            # stop hub service
muxd -service status-hub          # check hub service status

Hub CLI flags

Configuration keys

Config keys are split into two groups: hub (coordinator settings) and node (daemon registration).

Hub group (/config hub)

Node group (/config node)