Client Setup

Run muxd on a single machine. The TUI connects to a local daemon over HTTP/SSE. This is the default mode and the simplest way to get started.

First run

# Start a new session
muxd

# Resume the latest session
muxd -c

# Show version
muxd -version

# Use a specific model
muxd -model claude-opus

Set your API key:

/config set anthropic.api_key sk-ant-...

Or via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Daemon mode

Run muxd as a headless background daemon. Multiple TUI clients can connect to the same daemon.

muxd --daemon                     # start daemon on localhost
muxd --daemon -bind 0.0.0.0       # daemon accessible from LAN / mobile

The daemon listens on port 4096 by default. When you run muxd (without --daemon), it auto-discovers a running daemon via lockfile or starts an embedded one.

Running on a remote client

Run muxd on a remote machine and connect from your phone, laptop, or any device on your network.

1. Install and configure

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

# Create config directory and add your API key
mkdir -p ~/.config/muxd
cat > ~/.config/muxd/config.json << 'EOF'
{
  "anthropic_api_key": "sk-ant-...",
  "daemon_bind_address": "0.0.0.0"
}
EOF
chmod 600 ~/.config/muxd/config.json

Setting daemon_bind_address to 0.0.0.0 allows connections from other devices. Without it, muxd only listens on localhost.

2. Install as a system service

muxd -service install
systemctl --user start muxd
systemctl --user enable muxd

Enable lingering so the service runs even when you're not logged in via SSH:

loginctl enable-linger

3. Open the firewall

The default daemon port is 4096.

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 auto-discovers the daemon, or connect directly with muxd -c
• iOS app: Run muxd once on the server, type /qr, scan the code, then /exit — the daemon stays running. The token is also printed as text for manual entry.
• Remote TUI: muxd --remote <host>:4096 --token <token> (get the token from /qr output)

Cloud instances (AWS, GCP, etc.): /qr shows local IPs (e.g. 172.31.x.x) which aren't reachable from outside the VPC. Use your instance's public IP instead — find it in your cloud console or with curl ifconfig.me.

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

systemctl --user status muxd

Service management

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

CLI flags