Skip to content

Getting Started

Jump to bottom
Ken Tobias edited this page Jun 22, 2026 · 5 revisions

Getting Started

Prerequisites

  • Rust toolchain on both client and server (rustup.rs)
  • SSH access to the remote host (passwordless recommended)
  • etrs in PATH on the remote host — installed automatically alongside etr via cargo install

Install

cargo install etr

This installs two binaries to ~/.cargo/bin:

  • etr — the client you run locally
  • etrs — the server binary that etr starts on the remote host via SSH

The remote host needs etrs in its PATH. If the remote also has Rust installed, run cargo install etr there too. Otherwise copy the etrs binary manually and ensure it's in PATH for SSH sessions (add ~/.cargo/bin to PATH in ~/.bashrc or ~/.zshrc).

Connect

etr user@host

etr will SSH to the host, start etrs in the background, and hand off to a persistent QUIC session. You'll see your normal shell prompt. From this point, your session survives network drops, laptop sleeps, and Wi-Fi switches.

Run a remote command

Pass a command after the host to run it instead of an interactive shell. The client exits when the command exits.

# Run a full-screen TUI program
etr user@host btop

# Shell syntax works (pipes, redirects, env vars)
etr user@host 'distrobox -- btop'

# Multi-word commands without quoting
etr user@host ls -la /tmp

LANG, LC_*, COLORTERM, and TERM_PROGRAM are automatically forwarded from your local environment so TUI programs get the right locale and color depth.

Common variations

# Non-standard SSH port
etr -s 2222 user@host

# etrs is not in PATH — specify the full path
etr --server-path /home/user/.cargo/bin/etrs user@host

# Verbose output (see connection events)
etr -v user@host

# Full packet trace for debugging
etr -vvv user@host

Test on localhost

A quick sanity check before using on a remote host:

# Make sure passwordless SSH to localhost works
ssh-copy-id localhost

# Connect
etr localhost

Force-disconnect escape sequence

If the server becomes unresponsive, type ~. (tilde then dot) at the start of a line to force the client to exit immediately — the same escape as SSH and mosh.

Detaching and reattaching

etr does not currently support detach/reattach from the CLI (the session lives as long as the etr process). If your etr process is killed without sending a clean Disconnect, the server keeps your shell alive for 30 minutes, and a new etr invocation will start a fresh session (not reattach).

Uninstall

cargo uninstall etr

Clone this wiki locally