Client Setup

muxd is the terminal TUI client. It connects to a local daemon or a remote hub. Pure client — no agent logic.

Quick start

# Start the daemon first (separate binary)
muxd-daemon

# Start the TUI (auto-discovers the daemon)
muxd

The TUI auto-discovers the daemon via a lockfile at ~/.local/share/muxd/server.lock. If the daemon is running, it connects. If not, it prints a helpful error:

No muxd-daemon found.

Start one with:
  muxd-daemon

Or connect to a remote:
  muxd --remote host:4097 --token <token>

CLI flags

muxd has three flags:

muxd --version
muxd --remote hub.example.com:4097 --token abc123

Connecting to a hub

When you connect with --remote, the TUI shows a node picker listing all daemons registered with the hub. Pick a node to start a session.

muxd --remote hub.example.com:4097 --token <token>

Switch nodes from inside the TUI with /nodes.

First run

Set your API key inside the TUI:

/config set anthropic.api_key <your-key>

Or set it before starting via environment variable:

# Linux / macOS
export ANTHROPIC_API_KEY=<your-key>
muxd

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "<your-key>"
muxd

Running on a remote server

Install the daemon on a remote server and connect from your laptop or phone.

1. Install and configure

# Install
curl -fsSL https://raw.githubusercontent.com/batalabs/muxd/main/install.sh | bash

# Set your API key
mkdir -p ~/.config/muxd
echo '{"anthropic_api_key":"<your-key>"}' > ~/.config/muxd/config.json

2. Install as a system service

# Linux / macOS
muxd-daemon -service install
systemctl --user start muxd-daemon
systemctl --user enable muxd-daemon

# Windows (PowerShell)
muxd-daemon -service install
muxd-daemon -service start

On Linux, enable lingering so the service runs without an active SSH session:

# Run as root, replace YOUR_USER
loginctl enable-linger YOUR_USER

3. Open the firewall

The daemon listens on port 4096 by default.

Fedora / RHEL (firewalld):

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

Ubuntu / Debian (ufw):

sudo ufw allow 4096/tcp

4. Connect

From any device on the same network:

• Terminal: muxd --remote <server-ip>:4096
• iOS app: Run muxd-daemon once on the server. Type /qr in a TUI session to get a QR code, then scan it in the app.
• Another server: Connect through the hub with muxd --remote <hub-ip>:4097 --token <token>

Cloud instances (AWS, GCP, etc.): Set MUXD_BIND=0.0.0.0 so the daemon accepts connections from all interfaces. The daemon auto-resolves to your actual LAN IP for hub registration.

The daemon survives SSH disconnects and reboots. Check its status anytime:

# Linux
systemctl --user status muxd-daemon

# Any OS
muxd-daemon -service status

Service management

muxd-daemon -service install     # install as OS service
muxd-daemon -service uninstall   # remove service
muxd-daemon -service start       # start service
muxd-daemon -service stop        # stop service
muxd-daemon -service status      # check service status

Daemon environment variables

The daemon reads these env vars (overrides config.json):