How to use SetuSSH: SSH, SFTP, tunnels and shortcuts

Install

Get the current build from the Download page. The Windows and macOS builds are not code-signed yet, so both systems warn once on the first launch. The steps below get past that. Every release also ships a SHA256SUMS file, and the Download page shows how to check a file against it.

Windows

1. Download SetuSSH-Setup-<version>.exe and run it.
2. SmartScreen reports an unknown publisher. Click More info, then Run anyway.
3. Accept the licence and pick an install folder. The installer adds a Start menu entry and a desktop shortcut.

macOS

1. Open the .dmg (arm64 for Apple Silicon, x64 for Intel) and drag SetuSSH into Applications.
2. The first launch is blocked by Gatekeeper because the build is not notarised. Either clear the quarantine flag in Terminal, or open System Settings, go to Privacy & Security, and click Open Anyway under the message about SetuSSH.

   xattr -cr /Applications/SetuSSH.app

3. Open SetuSSH from Applications. macOS remembers the choice.

Linux

Three ways to install. The apt repository is the one to pick on Ubuntu or Debian: installs are checked against the SetuSSH signing key and updates arrive with apt upgrade.

curl -fsSL https://setussh.com/apt/setussh.gpg \
  | sudo tee /usr/share/keyrings/setussh.gpg > /dev/null

echo "deb [signed-by=/usr/share/keyrings/setussh.gpg] \
https://setussh.com/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/setussh.list

sudo apt update && sudo apt install setussh

The .deb on the Download page is the same package as a one-off file. It installs with sudo apt install ./SetuSSH-*-amd64.deb and will not update itself. apt notes that the file is not from a signed repository; that is expected for a local file.

The AppImage runs on any distribution once it is executable (chmod +x SetuSSH-*.AppImage). It needs libfuse2 (sudo apt install libfuse2). On Ubuntu 24.04, Debian 12 and newer, where unprivileged user namespaces are restricted, start it with --no-sandbox. The .deb does not have this problem: its post-install step sets up the sandbox helper.

Your first connection

Quick connect

1. In the ribbon, the Session group has a box marked ssh. Type user@host:port, for example deploy@203.0.113.10. The port defaults to 22. Leave out the user and the dialog suggests root.
2. Press Enter or click Connect.
3. If a saved session already matches, it opens. Otherwise the session dialog opens with those fields filled in, and you finish it as below.

The session dialog

Press Ctrl+Shift+T, click New in the ribbon, or + New at the top of the sidebar.

1. Fill in a name, the host, the port and the username.
2. Pick an auth method. Password is saved encrypted through the OS keychain. Private key takes a file (click Browse) and an optional passphrase. SSH agent uses your running agent, or Pageant on Windows.
3. Folder, jump host, tags and notes are optional. Click Create.

The session is saved in the sidebar and a tab opens. Passwords need the OS keychain (DPAPI, Keychain or libsecret). Without one, SetuSSH still works with key and agent auth and only refuses to store the password. Or set a master password under Settings, Security: saved passwords are then encrypted with it instead of the keychain, on any OS.

The host key check

On the first connect to a server, a Verify host key dialog shows the host, the key type and the fingerprint. Compare the fingerprint with what the server's owner gave you, leave Remember this host ticked, and click Accept. Reject or Esc closes the dialog without connecting.

If the key does not match the one saved earlier, the header turns red and says the host key has changed, with the old fingerprint struck through. This happens when a server is reinstalled, and it also happens when someone is intercepting the connection. Reject is the default and the box to replace the saved key is unticked. Choose Accept anyway only when you know why the key changed.

Through a jump host

In the session dialog, Jump host / gateway lists your other saved sessions. Pick the bastion and SetuSSH connects to it first, then opens the session through it, the way ProxyJump does in OpenSSH. The bastion can have a jump host of its own, so chains work. Each hop gets its own host key check.

Saved sessions and folders

The sidebar's Sessions tab lists every saved server. A single click selects a row. Double-click it, or press Enter, to connect. Hover a row to see its address in the tooltip and to reach the star, the pencil (edit) and the cross (delete). Ctrl+Shift+B hides and shows the sidebar.

• Click + Folder at the top of the sidebar to make a folder, then drag a session row onto a folder header to file it. Every valid target lights up while you drag. Deleting a folder keeps its servers and moves them to the top level.
• Click the star on a row to make it a favourite. Favourites appear in their own group at the top as well as in their folder.
• Tags are set in the session dialog, comma separated. They show under the name, and clicking one filters the list to that tag.
• The filter box matches name, host, username, tags and notes. tag:web narrows the list to one tag.

Import from ~/.ssh/config

Click SSH config in the ribbon's Backup group. SetuSSH reads the Host blocks in ~/.ssh/config, following Include lines and skipping wildcard patterns. Tick the hosts you want. Ones already saved are marked. A host with an IdentityFile imports with key auth; the rest use the agent. A ProxyJump becomes a jump-host link when the hop is among the imported or saved sessions.

Backup and restore

Export in the Backup group writes a .json file with your sessions, folders, tunnels and known hosts. It asks whether to include passwords and passphrases. They are written as plain text, so the safe answer is no. Import reads that file back on another machine.

Tabs and split panes

Each connection is a tab. Ctrl+Tab and Ctrl+Shift+Tab move between tabs, Ctrl+Shift+1 to Ctrl+Shift+9 jump to a numbered one. Double-click a tab to rename it and drag it to reorder. The dot on the tab shows the connection state.

1. Press Ctrl+Shift+\ to split the focused pane to the right, or Ctrl+Shift+- to split it downwards. The new pane opens a second shell on the same server. The same actions are in the ribbon's View group and in the terminal's right-click menu.
2. Drag the divider between panes to resize them. With the divider focused, the arrow keys move it too.
3. Ctrl+Shift+] and Ctrl+Shift+[ move focus to the next and previous pane. Clicking into a pane focuses it as well.
4. Ctrl+Shift+W closes the focused pane. Closing the last pane closes the tab.

Once a tab is split, each pane gets a slim header with its status dot, its title, a close cross and, when MultiExec is on, a broadcast tick. The focused pane has an accent outline, and the ribbon's Split, Reconnect and Duplicate buttons act on it.

Duplicate opens the same server in a new tab. Reconnect replaces the shell in the focused pane with a fresh one; the tab's tunnels and Files view keep working. Both are in the ribbon, the command palette and the right-click menu. When a connection drops, the pane prints a short banner: R reconnects, S saves the scrollback to a file and X closes the pane.

Local terminal

Press Ctrl+Shift+` or click Local in the ribbon's Session group to open your own shell (zsh, bash or PowerShell) as a tab. It splits like any SSH pane: Ctrl+Shift+\ or Ctrl+Shift+- opens a second local shell beside it. When the shell exits, the pane prints [shell exited]; press R to start it again. For a local pane the ribbon's Reconnect button reads Restart and does the same.

Files

The sidebar's Files tab is a file browser for the active SSH session, over SFTP on the connection you already have. The moment a session connects, the sidebar switches to it, starting in the login user's home directory. Ctrl+Shift+E, or SFTP in the ribbon's Tools group, brings it back at any time. The tab shows which host it is looking at.

1. Click a folder to enter it and the .. row to go up. The toolbar has up, home and refresh buttons, a toggle for hidden files, a filter box, a + button for a new folder and two upload buttons.
2. Type a path in the path box and press Enter. ~ is the home directory, and a path with no leading slash is relative to the folder on screen.
3. Drag files or folders from your file manager onto the list to upload them into the current folder, or onto a folder row to upload into that folder. Folders upload with everything inside them. The toolbar's upload buttons pick a file or a folder instead.
4. Right-click a row for Download, Edit locally (files), Copy path, Rename, Permissions (an octal mode such as 644) and Delete.

Edit locally opens the file in your usual editor, and every save uploads it again. Double-clicking a file does the same. While files are open this way, a pencil badge with a count sits in the toolbar; click it to stop editing and remove the temporary copies. Transfers show a progress overlay with the rate and the time left.

Drag the sidebar's right edge to make it wider. For a wide table with modified dates and a button for each action, click Panel in the View group (with the Tunnels panel closed): the same browser opens across the bottom of the window. To stop the sidebar switching to Files on every connect, open Settings (Ctrl+,), go to Files and turn off Show remote files on connect.

Tunnels

Press Ctrl+Shift+L or click Tunnels in the Tools group. The panel opens across the bottom and lists the tunnels of the active session. Tunnels are saved with the session, so they come back with it.

1. With a session tab open, click + Add tunnel.
2. Pick a kind. Local (-L) opens a port on this machine and forwards it to a host the server can reach. Remote (-R) opens a port on the server and forwards it to a host this machine can reach. Dynamic SOCKS5 (-D) opens a SOCKS5 proxy on this machine that routes any host through the server.
3. Set the bind address (127.0.0.1 by default) and the bind port. Local and remote tunnels also take a destination host and port. Tick Auto-start to open the tunnel whenever the session connects.
4. Click Start on the row. The status column reads running, with bytes in and out beside it, and the status bar counts running tunnels. Stop closes it; an error shows its message when you hover the status.

For example, a local tunnel from 127.0.0.1:8080 to localhost:80 lets you open http://127.0.0.1:8080 in a browser and reach the web server on the remote machine.

Type into several servers at once

1. Open a tab to each server.
2. Click MultiExec in the Tools group to turn broadcast on. A tick box appears on every tab and, in split tabs, on every pane header.
3. Tick the terminals to include. The one you type in must be ticked too. The status bar shows broadcast with the count, and the ribbon button shows the same number.
4. Type in any ticked terminal. Every keystroke goes to all of them, so one sudo apt update lands on each server. Untick a terminal to leave it out, or click MultiExec again to turn broadcast off.

AI assistant

The assistant is a panel that works in your open terminal. You bring your own API key; SetuSSH has no model of its own. It is part of the first 7 days and of a licensed install; the free tier does not include it.

Set it up

1. Click AI in the Tools group. The panel opens on the right; a button in its header docks it on the left instead, and its inner edge drags to resize.
2. Click Add AI provider. Pick Anthropic, OpenAI, DeepSeek or Ollama, or Custom for any other OpenAI-compatible endpoint such as vLLM, LM Studio or OpenRouter.
3. Give it a name. The OpenAI, DeepSeek and Ollama presets fill in the base URL; for Custom, paste one that ends at /v1 (https://api.openai.com/v1, http://localhost:11434/v1 for Ollama). Anthropic needs none. Paste the API key, or leave it blank for a local Ollama. Click Save.
4. The model list is fetched from the provider. Pick one from the drop-down at the top of the panel.

If ANTHROPIC_API_KEY or OPENAI_API_KEY is set in your environment, SetuSSH uses it without any pasting. Keys are stored encrypted on this machine and never leave the main process, except to the provider you chose.

How it works

Type a question about the active server, such as why nginx is down or what is filling the disk, and press Enter. Commands run in your open terminal, so you watch them happen, and the assistant reads the output back.

• Read-only commands run on their own. Anything that changes the machine, writes a file or manages SetuSSH itself shows a card with the command (and a diff for a file write) and waits. Click Approve, Approve all to skip the prompt for that kind of action while it works on this message, or Deny. Destructive commands always ask.
• Destructive commands such as rm, mkfs and shutdown always ask, whatever the permissions say.
• Stop sends the shell an interrupt (the same as Ctrl+C) and halts the assistant.
• A large output is not sent to the model in one go. The model gets an excerpt and then reads the rest in pages or searches it, so a long log is worked through in parts rather than dropped.
• The settings button in the panel header sets permissions per category (read, run, write, manage the app, memory) to auto, ask or deny, for all servers or for the active one, and keeps memory notes about each server. Token counts and an estimated cost show under the conversation.

Other AI tools, through MCP

SetuSSH can also work for an AI client you already use, such as Claude Code, Claude Desktop or Cursor. Open Settings, go to AI access and turn on Let AI clients use this SetuSSH. A Model Context Protocol server starts at http://127.0.0.1:30838/mcp, on this machine only, and every request must carry the access token shown there. The client can then see your saved servers, open them as tabs you can watch, run commands, type into terminals and move files, as far as the Access setting allows; it starts at Read-only. Connect an AI client (MCP) has the setup for each client, every tool, and what each access level allows.

Licence and plans

For the first 7 days after the first launch, everything is on: unlimited saved sessions and the AI assistant, with no key, account or card. The plan badge at the right of the status bar reads trial with the days left.

After that SetuSSH keeps working on the free tier. The 10 oldest saved sessions stay connectable, later ones show a padlock in the sidebar until a key is entered, and the AI assistant is off. Nothing is deleted. The badge reads free tier.

1. Request a key on this site. Each request is read by a person, and the key arrives by email from support@setussh.com.
2. In SetuSSH, click the plan badge in the status bar. A dialog opens with a box for the key.
3. Paste the whole key from the email (it starts with SETU1) and click Unlock. The badge changes to licensed. The key is checked on this machine, so it keeps working offline.

If the badge reads check clock, the computer's date has moved backwards. Set it correctly and reopen SetuSSH. For anything about a key or a request, write to support@setussh.com.

Shortcuts

App shortcuts all use Ctrl+Shift, so a plain Ctrl key still reaches the remote shell, tmux or vim. Ctrl is Cmd on macOS, and F1 shows this list inside the app.

Reconnect and Duplicate have no shortcut on purpose: on macOS Cmd+Shift+R is force reload. They live in the ribbon, the command palette and the terminal's right-click menu, which also has copy, paste, select all, clear screen, find, logging to a file and zoom.