ControlMaster

The client can leverage SSH ControlMaster mode to share multiple SSH sessions over a single network connection.

This improves connection speed and avoids repeating the authentication process for each session.

Prerequisites

ControlMaster requires an OpenSSH client with Unix-domain control sockets. It is not supported on Windows because OpenSSH for Windows does not provide the required behavior.

Quick usage

Enable connection reuse for one command:

tealc ssh AGENT_NAME --control-master

Or enable it by default in tealc.yaml:

control-master: true

The short option is -M.

Supported commands

VS Code behavior

tealc vscode has no -M option of its own. VS Code’s Remote-SSH extension makes several connections through the generated ssh and scp wrappers. To reuse those connections, set control-master: true in the persistent client configuration before launching VS Code.

Connection lifecycle

The master connection is created automatically on first use: the first -M command run against an agent while no master is active establishes it, and every subsequent -M command reuses that shared connection, skipping the authentication and password prompt.

This applies to every command listed above, not just tealc ssh. For example, running tealc clip get AGENT -M with no master already open will start one and leave its socket in place for later commands to reuse.

Once established, the master stays alive in the background for a short idle period (ControlPersist) after the last session ends, then exits on its own. The next -M command after it has expired simply establishes a new one.

Limitations

• tealc delete uses the HTTP API and does not use ControlMaster.
• tealc ssh AGENT --no-ssh performs forwarding without an interactive SSH session and does not establish a master connection.
• The control socket is local operator state. Do not copy or share it between users.