CLI reference

Targets use <profile>/<hostname>. Optional short aliases are read from your configuration.

Dashboard and status

tailmux
tailmux dashboard
tailmux monitor [--json]
tailmux monitor claude-setup
tailmux monitor claude-statusline
tailmux status
tailmux status --json

Bare tailmux opens the interactive dashboard in a terminal and prints help when redirected. The dashboard configures profiles, SSH hosts, forwards, public URLs and terminal defaults, and opens terminals and setup workflows. Status inspection does not start the daemon. See dashboard controls.

Host setup and port discovery

tailmux setup check lab/worker
tailmux setup check --all --json
tailmux setup install lab/worker --tmux --ports
tailmux setup orca lab/worker --local-port 16768
tailmux setup orca lab/worker --local-port 16768 --apply
tailmux ports lab/worker
tailmux ports lab/worker --json
tailmux ports lab/worker --pick
tailmux ports lab/worker --forward

setup install requires explicit package flags and runs remote sudo interactively. setup orca accepts --remote-port (default 6768) and --replace with --apply for an existing stopped unit. It does not install Orca or configure persistent firewall rules. ports lists TCP listeners and visible process names; --pick prints a selected port, while --forward forwards it to the same local port. See host setup and ports.

Account setup

Host options

tailmux hosts add lab/worker \
  --user developer \
  --address worker.example.ts.net \
  --port 2222

Options follow the target. Omitted options retain the host's existing values, or default to the target hostname, port 22, and the SSH default user.

Connections

See tailmux help <command> or tailmux <command> --help for CLI usage without opening a connection.

Orca runtimes

serve also accepts --ready-file. This is native orca serve integration; runtime installation and firewall setup are prerequisites. See Orca remote runtimes.

Terminal with a box picker

tailmux terminal
tailmux terminal --backend zellij lab/worker
tailmux terminal --default tmux

--backend tmux|zellij overrides this launch; put options before the host. --default tmux|zellij saves the preference without launching. The initial default is tmux. Install fzf and the chosen backend locally, and tmux on remote hosts.

Alt+B opens the box picker in either backend. Zellij also supports Ctrl+B in normal mode or F2 when unlocked; tmux also accepts Ctrl+B, B. Splits in a host window/tab open independent persistent shells there. Detach with Ctrl+B, D in tmux or Ctrl+O, D in Zellij. Remote shells remain running.

See the terminal guide for pane naming, locked mode and remote-session behavior.

Isolated loopback names

tailmux loopback setup lab/worker
tailmux loopback setup lab/worker --name worker.test
tailmux loopback list

setup previews the dedicated address, hostname and local operating-system changes, then asks Apply changes? y/N before invoking sudo. The default name is the host component plus .test. Assignments are stored in private loopbacks.json; system changes affect only this computer. list needs no administrator access.

Port forwarding

tailmux forward lab/worker 3000
tailmux loopback setup lab/worker --name worker.test
tailmux loopback setup other/builder --name builder.test
tailmux loopback list
tailmux forward lab/worker 3000-3005 --name worker.test
tailmux forward other/builder 3000-3005 --name builder.test
tailmux forward lab/worker 8080:3000,9090:9000 --json
tailmux forward --resume <saved-name>
tailmux forwards [--json]
tailmux unforward <id>

Ports accept individual numbers, inclusive ranges, comma-separated lists and local:remote mappings, up to 100 ports per group. Options follow the host and may appear before or after ports.

Without a name, forwarding carries raw TCP to remote loopback. With a name, the HTTP proxy rewrites direct localhost redirects and JSON URLs for ports in the group, and removes loopback cookie domains while retaining security attributes. JSON rewriting is limited to 2 MiB. HTML, JavaScript, HTTPS URLs and external OAuth callback parameters are not rewritten. OAuth allowlists and application HTTPS requirements may still need configuration.

Raw TCP and managed public listeners bind to 127.0.0.1. Private named listeners require tailmux loopback setup <host> [--name NAME]; the default name is <host>.test. Setup assigns a dedicated 127.77.x.y address per canonical box and updates this computer's /etc/hosts, allowing boxes to reuse a port. .localhost is rejected because browsers force it to 127.0.0.1. On macOS, setup installs a launchd job to restore the address at boot. A wildcard 0.0.0.0 listener can still conflict.

Forwards keep running after the CLI exits. Use --save NAME to restore a group when the daemon next starts. tailmux unforward <id-or-saved-name> stops and forgets a group; tailmux stop stops networking while retaining saved definitions. SSH disconnections retry with capped backoff and remain visible in tailmux forwards. SSH must permit local forwarding, and your agent must be unlocked for batch authentication.

See the forwarding guide for DNS setup, rewrite boundaries, lifecycle details and publishing a selected port with Cloudflare or ngrok. Provider integration supports --cloudflare TUNNEL --url https://host or --ngrok --url https://host for a single port. Configure provider credentials and the stable hostname first.

tailmux loopback list reports the canonical box, assigned address and configured names. Loopback setup changes only the local computer and requires administrator access; it does not install anything remotely. After upgrading from the shared-loopback implementation, restart the old daemon with tailmux stop, configure the exact host/name for saved named forwards, and resume failed saved groups. A .test HTTP origin is not automatically a secure context, so some cookies, service workers and OAuth flows still require HTTPS or app configuration.

Local runtime

Errors return a nonzero exit code. Connection tests do not authenticate SSH. Bulk session listing reports per-host failures and exits nonzero if any host failed.

The old top-level attach and sessions commands remain compatibility aliases. Session output is now a table by default; add --json in scripts that consume JSON.

Not implemented yet

ports and run are proposed commands. They are not available in this version. See the roadmap.

Open this computer in the terminal

tailmux terminal local
tailmux terminal --backend tmux local
tailmux terminal --backend zellij local

The box picker lists local (this machine) first, followed by remote targets with aligned online/offline and saved labels. Local access works without a Tailscale profile or SSH connection. It opens your $SHELL as a login shell (falling back to /bin/sh); new panes in the local tab/window also run locally. Exiting the shell closes that pane. Keep the tab/window named local so new panes retain this routing.

local is reserved by terminal for this computer. Use the full profile/local target if a remote machine is also named local. Existing shortcuts open the same picker from local and remote tabs.