How to Use LazySSH: The Beginner's Guide (First Connection, Tunnels, and the SCP Arc)

CodexFuse Team · 2026-11-03T03:36:40.482Z · 13 min read min read

LazySSH is the open-source SSH connection manager for people juggling many servers: install with pipx, open persistent connections, build tunnels, and move files from one interactive prompt.

How to Use LazySSH: The Beginner's Guide (First Connection, Tunnels, and the SCP Arc)

Learning how to use LazySSH starts with one sentence: it is an open-source command-line manager that keeps your SSH connections, tunnels, file transfers, and automation in a single interactive prompt, so you stop retyping long ssh commands every time you hop between servers. You install it with one command, open a connection once, and that connection stays alive on a persistent control socket while you run tunnels, browse files, and fire off automation through it. This LazySSH tutorial walks the full beginner arc in order: install, the two interface modes, your first connection, saved configs, tunnels, the SCP file-transfer mode, and the plugin system.

One important note before we start: the name. This guide is about the Python CLI on PyPI — lazyssh, by Bochner, a terminal-based SSH connection manager — and NOT the Go project also called lazyssh (github.com/stephank/lazyssh), which is an SSH server that starts temporary VMs or EC2 instances on demand as a jump host. They share a name and nothing else. Also note that this site hosts LazySSH Studio, a practice tool with a simulated terminal — a safe playground for typing SSH-like commands in your browser, not the real CLI this guide teaches. Every fact below was verified against the project's own pages on November 3, 2026, including the PyPI release page, the package metadata API, and the project's reference documentation.

If the servers you are connecting to are VPS machines, our what is VPS hosting guide covers the infrastructure side — LazySSH is the companion idea: it is how you actually live inside those machines day to day. If you automate fleets of servers, our Ansible beginner guide covers automation over SSH at scale — LazySSH's plugin system is the interactive, one-server-at-a-time cousin of that world.

What Is LazySSH, Exactly?

LazySSH is a modern CLI for managing SSH connections, tunnels, file transfers, and automation from one interactive prompt — that is the project's own one-line summary on PyPI. It is free and open source under the MIT license, written in Python, and aimed at developers and system administrators who juggle many servers. As of November 3, 2026 the latest release is 1.6.6, published February 21, 2026; the project is marked Production/Stable on PyPI, the GitHub repository (github.com/Bochner/lazyssh) dates to February 15, 2025 and carries 232 commits across 32 releases.

The architecture is the whole pitch: connections run over persistent SSH control sockets, so one authenticated connection is reused by your shell sessions, your tunnels, and your file transfers instead of re-authenticating for each. That persistence is what makes the rest of the tool fast — open once, then everything flows through the open socket.

How Do You Install LazySSH?

You install LazySSH with pipx — that is the recommended path, and the one to use unless you have a reason not to. The system requirements are modest: Python 3.11 or newer (the package classifiers list 3.11, 3.12 and 3.13) and an installed OpenSSH client, which provides the actual SSH transport underneath. Supported platforms are macOS and Linux; there is no Windows support in the package classifiers, so Windows users should plan accordingly.

pipx install lazyssh
# or, if you prefer pip:
pip install lazyssh

If you want to build from source, the project's documented path is to clone the repository, then build with Hatch and install the resulting wheel — Hatch is the project's build backend, so a plain setup.py flow is not the intended route. The package pulls in a modest dependency set (click, rich, prompt-toolkit, paramiko, pexpect and a few others, per the PyPI metadata API). Optionally, the Terminator terminal emulator can be installed — LazySSH falls back to your native terminal automatically if it is not present, and you can switch the terminal method at runtime with the terminal command or the LAZYSSH_TERMINAL_METHOD environment variable.

What Are the Two Interface Modes?

LazySSH ships two interfaces for the same engine. Command Mode is the default: an interactive prompt (lazyssh>) with tab completion, where you type commands and the tool completes server names, commands, and flags. Prompt Mode is a numbered menu — create connection, create tunnel, destroy tunnel, open terminal, close connection, switch to command mode, exit — for people who prefer guided choices over typing.

You start in menu mode with lazyssh --prompt, and you switch between modes inside the tool with the mode command. Beginners who are unsure of the command names should start in menu mode once, then graduate to command mode where everything is one tab-complete away. The full command reference lives in the project's docs/reference.md, with getting-started, guides, troubleshooting, and maintainer docs alongside it in the repository.

How Do You Open Your First SSH Connection?

You open your first connection with one command that names the server, the user, and a label for the connection — the label is the name you will reuse for everything that follows. Here is the direct answer, as a five-step arc a beginner can finish in minutes:

1. Install. pipx install lazyssh, then type lazyssh to open the interactive shell.
2. Create the connection. Type lazyssh -ip 192.168.1.100 -port 22 -user admin -socket myserver -ssh-key ~/.ssh/id_ed25519 — the documented example from the project's own quick start. The -socket name is your handle; -ssh-key points at your existing SSH key.
3. Check it is alive. list shows your active connections and tunnels in a status table.
4. Open a shell on it. open myserver drops you into a shell session on the named connection in your current window.
5. Save it before you leave. save-config myserver persists the connection parameters so next time you start LazySSH it is one command away instead of a retyped flag list.

The thing to internalize from this arc is the control socket: the connection in step 2 stays open as a persistent SSH control socket, and steps 4 and 5 — plus the tunnels and file transfers below — all reuse it. That is why the first connection feels like setup and everything after feels instant. If the connection behaves oddly, debug and the --debug flag raise the log level; debug logs land in /tmp/lazyssh/logs.

How Do You Save and Reuse Connections?

You save a connection with save-config <name>, and LazySSH writes it to /tmp/lazyssh/connections.conf — a file kept at 600 permissions, which matters because it holds your connection details. The sections are TOML-style, keyed by the connection name, with fields for host, port, username, socket name, SSH key path, shell, and proxy port.

The saved-config commands round out the workflow: connect <name> reopens a saved connection, config shows what is saved, delete-config <name> removes one, and backup-config backs the file up. Passing lazyssh --config /path/to/connections.conf points the tool at a saved-config file at startup — the default path is /tmp/lazyssh/connections.conf. The practical habit is simple: any server you touch more than twice gets a saved config with a memorable socket name.

How Do SSH Tunnels Work in LazySSH?

You build tunnels with tunc (tunnel create) against an already-open connection, and remove them with tund (tunnel delete) by tunnel ID. Three tunnel kinds are supported: forward tunnels, reverse tunnels, and dynamic SOCKS tunnels. The commands read like sentences:

tunc myserver l 8080 localhost 80      # forward: local 8080 -> remote localhost:80
tunc myserver r 9000 localhost 3000     # reverse: remote 9000 -> local localhost:3000

For the SOCKS case, add -proxy when creating the connection — without a value it uses port 9050 per the current reference documentation. (Older README text mentioned 1080; use 9050 on current releases.) list shows your tunnels in the project's friendly status tables, and tund <tunnel_id> removes one. The guided alternative is wizard tunnel, which walks you through building a tunnel question by question — a good first run before you memorize the tunc syntax.

The tunnel workflow pairs naturally with persistent sessions on the remote side: if you keep long-lived terminal sessions on your servers, our tmux beginner guide covers detaching and reattaching to them — LazySSH manages the connection to the box, tmux manages the session inside it.

How Do You Transfer Files in SCP Mode?

You enter SCP mode with scp <connection>, and you get a small file browser for the remote server that reuses the open control socket — no new authentication, no new connection. The mode has its own command set, arranged here as the project's reference documentation lists them:

The honest use case is interactive file work: grabbing a log directory after an incident, pushing a config file to a staging box, pulling down a backup before a migration. The progress indicators and batch downloads are the features raw scp never gave you, and because transfers ride the open socket, a ten-file batch feels like one operation. For scripted, unattended copies, keep using rsync — SCP mode is for hands-on work.

What Can You Automate With Wizards and Plugins?

Wizards are the guided half: wizard lazyssh walks you through creating a connection step by step, and wizard tunnel does the same for tunnels. They exist so the first run is a conversation rather than a man page — run them once, then switch to the direct commands.

Plugins are the automation half. plugin list shows what is installed and plugin run <name> <connection> runs a plugin against an open connection, reusing the control socket. The built-in enumerate plugin is the showcase: it runs one batched remote script that collects system, user, network, filesystem, and security telemetry, then reports Quick Wins grouped by difficulty (Instant, Easy, Moderate), a Priority Findings table with severity badges and inline exploit commands, GTFOBins cross-references, and a kernel exploit suggester covering roughly 15 CVEs — saving both a survey_<timestamp>.json and a plain-text summary, with a --json flag for machine-readable output. Custom plugins are plain Python or shell scripts, which makes the plugin system the place to park any recurring check you run across your fleet. That automation instinct scales further with Ansible — see our Ansible beginner guide for the fleet-wide version of the same idea.

Should You Replace Raw ssh With LazySSH?

Not everywhere — replace it where connections, tunnels, and files dominate your day, and keep raw ssh where it is already the right tool. This decision table is the honest version of that tradeoff:

The pattern is consistent: LazySSH wins at interactive, multi-server daily work; the Unix primitives win at one-offs and scripts. Most sysadmins will end up using both.

7 Beginner Mistakes With LazySSH

Every one of these comes from misreading the model above. Avoid them and the tool does exactly what it promises:

Sources

• LazySSH on PyPI (pypi.org/project/lazyssh) — the project's one-line summary, install commands (pipx recommended), version 1.6.6 released February 21, 2026, system dependencies, platform support
• PyPI JSON metadata API for lazyssh — Python requirement (>=3.11), MIT license, full dependency list, package classifiers
• The LazySSH GitHub repository (github.com/Bochner/lazyssh) — README highlights, docs directory (getting-started, reference, guides, troubleshooting, maintainers), repository stats (232 commits, 32 releases, created February 15, 2025)
• The LazySSH reference documentation (docs/reference.md) — command list, tunnel commands, SCP mode commands, config file schema, environment variables, plugin documentation, the enumerate plugin details
• pkg.go.dev/github.com/stephank/lazyssh — the unrelated Go project sharing the name (SSH server for on-demand jump hosts, AGPL v3)
• The Marco Polo backups article (marcopolo.io/code/backups-made-simple/) — the Go lazyssh in use as an on-demand backup jump host

Frequently Asked Questions

Is LazySSH free?

Yes. LazySSH is free and open source under the MIT license — there is no paid tier in the project's documentation, and the PyPI page lists no commercial offering. You install it with pipx and every feature (connections, tunnels, SCP mode, plugins) comes with it.

What is the difference between LazySSH and the Go project also called lazyssh?

They are unrelated projects that share a name. This guide covers the Python CLI on PyPI (github.com/Bochner/lazyssh, MIT license): an interactive SSH connection manager. The Go project (github.com/stephank/lazyssh, AGPL v3) is an SSH server that starts temporary virtual machines or EC2 instances on demand and serves them as jump hosts — you use it with ssh -J lazyssh. Check which one a search result describes before following its instructions.

Can I use LazySSH on Windows?

Not per the package metadata. The PyPI classifiers list macOS and POSIX/Linux, with an OpenSSH client as the system dependency — Windows is not listed. If your fleet work happens on Windows, plan on a macOS or Linux machine for the LazySSH side.

Where does LazySSH store my saved connections?

In /tmp/lazyssh/connections.conf, a file kept at 600 permissions. Sections are TOML-style, keyed by the connection name you chose, with fields for host, port, username, socket name, SSH key path, shell, and proxy port. The backup-config command backs this file up, and --config lets you point LazySSH at a different config file at startup.

Does LazySSH change how my SSH keys work?

No. LazySSH sits on top of your OpenSSH client — the project's documented connection example passes your existing key with -ssh-key ~/.ssh/id_ed25519, and the reference documentation's default for the SSH path is /usr/bin/ssh. Your keys stay where they are; LazySSH just reuses the authenticated connection through persistent control sockets so tunnels, file transfers, and plugins do not re-authenticate.