Configuration

Where files live

Override the directory with TAILMUX_HOME. Use a short, private path because Unix socket paths have a length limit.

export TAILMUX_HOME="$HOME/.tailmux"

Changing this directory selects a different set of profiles and identities. Do not change it casually after logging in.

Config file

{
  "terminal_backend": "zellij",
  "profiles": ["personal", "work"],
  "hosts": {
    "personal/devbox": {
      "profile": "personal",
      "address": "devbox",
      "user": "developer",
      "port": 22
    }
  }
}

The default configuration is empty. login adds profiles; hosts add saves machines. Host changes take effect on subsequent requests.

Terminal preference

terminal_backend is optional. Without it, tailmux terminal uses tmux. Save a preference with tailmux terminal --default tmux or tailmux terminal --default zellij; this does not open a terminal. --backend overrides one launch without changing the saved preference. Put terminal flags before the host.

Generated multiplexer settings belong to Tailmux's dedicated session. Zellij's generated file is rewritten on launch; editing it is not a persistent customization interface. Existing remote shells retain their running wrapper until restarted.

Ordinary forward groups are runtime state. forward --save NAME stores a definition in private forwards.json and restores it when the daemon starts. unforward removes the saved definition; stop preserves it. Provider credentials remain managed by the provider CLI; connector logs and generated configuration are private files under public-tunnels/. Private named forwarding also stores per-box assignments in loopbacks.json; tailmux loopback setup uses those assignments to update this computer's loopback interface and /etc/hosts with administrator access.

The interactive tailmux dashboard configures profiles, saved SSH hosts and the terminal backend without editing JSON manually. Terminal target metadata is separate from visible tab names. See dashboard and terminal routing.

Directory contents

config.json          Profiles, saved hosts and terminal backend preference
orca.json            Non-secret Orca runtime routes
orca.lock            Serializes Orca pairing and route updates
daemon.sock          Private local control socket
daemon.log           Runtime diagnostics
config.lock          Serializes configuration changes
daemon.lock          Prevents duplicate daemons
forwards.json        Saved forward definitions
loopbacks.json       Dedicated per-box loopback addresses and names
loopbacks.lock       Serializes loopback assignment updates
terminal/
  zellij.kdl         Generated local Zellij configuration
  zellij-shell       Default-shell wrapper for remote panes
state/
  personal/          Persistent tsnet identity
  work/              Separate tsnet identity

Treat the state directory as private. Do not commit it or copy it between machines while an identity is active.

SSH settings

Key selection, 1Password agent paths, and ordinary SSH options belong in ~/.ssh/config. Tailmux's host configuration provides only the profile, destination address, user, and port.

Stopping and restarting

tailmux stop
tailmux doctor personal/devbox

The second command starts a new daemon automatically. A stop closes active local transports but preserves the identity files and saved forward definitions. Herdr and dedicated tmux shells continue on remote hosts. Forwards save automatically and restore when networking starts. On macOS, loopback setup installs a boot job to restore dedicated address aliases.

Zellij reuses a running local session when you detach. Closing a tab with Ctrl+T, then X removes it. After closing the last tab, the next tailmux terminal starts a fresh session. Tailmux disables disk-layout resurrection so previously closed tabs cannot return from an old snapshot. Remote tmux shells remain on their hosts; this does not stop remote processes.

Dashboard hidden-box preferences are stored in hidden_boxes, keyed by the full target (or local). Use h to hide a selected box and H to reveal hidden entries for restoration. These preferences do not remove hosts or stop connections.