Remote execution + live view via tmate

A set of 3 utilities to:

• allow agents/scripts to execute commands on remote server and receive stdout
• let you connect to a live terminal session and see what the agent is doing
• without dealing with tmux attach, broken TTYs, and other pain

Commands:

• rtmate init — initialize and start a tmate session on remote server
• rtmate run — executes a command via SSH (stdout is returned), and mirrors it to tmate (if session is active)
• rtmate send — sends a command to a live tmate session (like "typing in terminal and Enter")
• rtmate attach — connect to the tmate session via SSH for interactive viewing
• rtmate status — check if the tmate session is active and show connection details

---

Requirements

On the remote server:

• tmate
• tmux (tmate uses tmux-compatible protocol/socket)
• bash

On the local machine:

• ssh
• base64

---

Installation

The repository is organized into two folders:

• client/ — scripts that run on your local machine:

  • tmate-run
  • tmate-send

• server/ — scripts that run on the remote server:

  • tmate-start

Setup

1. On the remote server: Copy scripts from server/ to a directory in your PATH (e.g., /usr/local/bin or ~/bin):

   cp server/tmate-start ~/bin/
   chmod +x ~/bin/tmate-start

2. On your local machine: Copy scripts from client/ to a directory in your PATH:

   cp client/tmate-run client/tmate-send ~/bin/
   chmod +x ~/bin/tmate-run ~/bin/tmate-send

---

Quick start

1) Initialize a session on remote server

On your local machine:

rtmate init

This will:

• Prompt you to select a remote host from your SSH config
• Install tmate-start on the remote server (if not already installed)
• Start a tmate session and cache the connection details locally

2) Connect to watch (optional)

rtmate attach

This connects you to the live tmate session via SSH, allowing you to watch commands execute in real-time.

(You can also use the web link from rtmate init output in a browser)

3) Run a command "for the agent", but make it visible in tmate

rtmate run "uname -a"

What happens:

• rtmate run executes the command via SSH and prints stdout locally (the agent sees it)
• The command is additionally "typed" into the tmate session (visible to anyone watching)

4) Type a command only into tmate (without stdout back)

rtmate send "htop"

---

Commands

rtmate init (local → remote server)

Initializes a tmate session on the remote server. Prompts for host selection from SSH config if not provided.

rtmate init [<host>]

What it does:

• Validates SSH connectivity
• Installs tmate-start on remote server (if needed)
• Starts tmate session and caches connection links locally
• Sets the host as current for subsequent run/send/attach commands

rtmate run (local → remote server)

Main command for agent execution.

rtmate run <command...>

• Always returns stdout/stderr to the current terminal (via SSH)
• Best-effort mirrors the command to tmate (if session exists)

rtmate send (local → remote server)

Sends a command into the tmate session via tmux send-keys.

rtmate send <command...>

This is a "UI command": you'll see the output in tmate, but won't get stdout in the terminal where you ran rtmate send.

rtmate attach (local → tmate session)

Connects to the tmate session via SSH for interactive viewing.

rtmate attach [<host>]

If no host is specified, connects to the current host's session. Use this to watch commands execute in real-time or interact with the session directly.

rtmate status (local → remote server)

Checks if the tmate session is still active and shows connection details.

rtmate status [<host>]

This validates that:

• The tmate socket exists on the remote server
• The tmate session is responsive
• Shows cached connection links and last initialization time

Use this to troubleshoot connection issues or verify session status before using attach.

---

Environment variables

For advanced usage and troubleshooting:

• REMOTE_HOST — override current host (e.g., for rtmate run and rtmate send)

tmate session configuration (cached per-host, rarely needed):

• TMATE_SOCK — path to socket (default: /tmp/tmate.sock)
• TMATE_TARGET — where to send send-keys (default: 0.0)

Mirror behavior for rtmate run:

• TMATE_RUN_MIRROR — 1/0 enable/disable mirroring to tmate (default: 1)
• TMATE_RUN_PREFIX — prefix for the string that the agent echo-prints in tmate before the command (default: [agent])

---

Troubleshooting

rtmate send not visible in tmate

Most likely incorrect TMATE_TARGET.

To see available panes:

rtmate run "tmate -S /tmp/tmate.sock list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_current_command}'"

Then set explicitly:

TMATE_TARGET="0.0" rtmate send "echo hi"

rtmate run doesn't mirror to tmate

First, check session status:

rtmate status

If the session is inactive, re-initialize:

rtmate init

You can also manually check that tmate is up and the socket exists:

rtmate run "ls -l /tmp/tmate.sock; tmate -S /tmp/tmate.sock list-sessions"

Cannot connect with rtmate attach

Check the session status first:

rtmate status

If the session is inactive or the tmate links have expired, re-initialize:

rtmate init
rtmate attach

---

Security notes

• Anyone who has the ssh/web link can connect to the session with the same level of access that tmate granted.
• Don't post links in public chats.
• If you need to stop sharing: close the tmate session on the remote server (exit) or kill the process.

---

Recommended workflow

1. Initialize session: rtmate init
2. (Optional) Open viewer: rtmate attach or use the web link
3. Agent executes commands via:
   • rtmate run "..." — to get stdout and simultaneously see commands in tmate
4. For interactive commands (htop/nano/etc): rtmate send "htop" and watch/control via rtmate attach