Ivan Kusalic - home page

Managing Multiple Servers With Tcon

Today I’m writing about my recent side project: tmux-connector, tcon for short. It is designed to help you manage multiple servers by employing SSH and tmux.

If you are managing more than a handful of servers, tcon could become an indispensable tool in your arsenal. It enables you to simultaneously connect to the servers and manipulate them as desired. You can issue the commands to a custom subset, or to all of the servers at once. All while tracking the progress through customisable layout, from the safety of your terminal.


Are you managing multiple servers as a part of your daily routine? Does this involve SSHing to a few of them? Maybe you need to monitor the load? Or install/upgrade some packages. Are you sometimes combing through the logs trying to figure out what’s going on? Or you just enjoy looking at the well-oiled system fulfilling your intention?

If that’s the case, meet the tmux-connector.

Tmux-connector is a ruby gem that exposes command-line interface: tcon. It splits your terminal in multiple windows (think tabs) and panes, using terminal multiplexer tmux. Each pane establishes a SSH connection to one of the servers. You can then use each pane as desired. You can also send the commands to the chosen panes, thereby executing them on the servers.

Here’s a simple demo1:

tcon demo (you can open the gif in a new tab if it’s too small)

How it works

You provide a SSH config file and a special tcon configuration file.

Tcon parses the SSH config file to obtain the list of host names. Host names are interpreted in accordance with tcon configuration file i.e. hosts are divided into different groups and sorting order is defined. The tcon configuration file can additionally define various desired properties, e.g.:

  • layout details (mapping from server connections to tmux panes and windows)
  • hosts can be ignored
  • multiple server groups can be merged together
  • multiple panes can be assigned to the same server
  • panes can exist without connections to servers

Once a session is created, that is, the layout is crated and the connections are established, you can get to work. You can use tmux panes to manually manipulate individual servers. Or you can use tcon send command to issue the commands to desired servers. Send command provides a few different mechanisms to specify target servers.

tcon send command
tcon send <session-name> (<command> | --command-file=<file>)
            [ --server-filter=<filter> | --group-filter=<regex>
              | --filter=<regex> | --window=<index> ]

  <session-name>             Name that identifies the session. Must be unique.
  <command>                  Command to be executed on remote server[s].
  <regex>                    String that represents valid Ruby regex.
  <index>                    0-based index.
  <filter>                   Filter consisting of a valid ruby regex and
                             optionally of a special predicate.
                             For more information see README file.
  -f --server-filter=filter  Filter to select a subset of the servers via
                             host names.
  -g --group-filter=regex    Filter to select a subset of the servers via
                             group membership.
  -r --filter=regex          Filter to select a subset of the servers via
                             host names or group membership.
                             Combines --server-filter and --group-filter.
  -w --window=index          Select a window via (0-based) index.
  -c --command-file=file     File containing the list of commands to be
                             executed on remote server[s].
  -v --verbose               Report how many servers were affected by the send

You can simultaneously work on different sessions. Sessions are also automatically persisted, so they can be resumed even after the computer restarts.


If you manage multiple servers on a (semi-)regular basis, give the tmux-connector a go.

Visit the project’s github page to learn more (documentation is quite extensive).

If you’d like to provide feedback, send me an email, I’d appreciate it.

  1. in the demo, I’m connection to some servers belonging to dev platform at cloudControl