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.
   terminalCopy

   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.

Coloured output

Plain output from the server is coloured to make the important parts easier to spot: links, IP addresses, the user@host:path prompt, and words such as error, warning and OK. It uses your colour scheme, and it leaves alone anything the server already coloured and full-screen programs such as vim and htop. To turn it off, open Settings, Terminal and switch off Highlight terminal output. The change applies at once to new output in every open terminal, and you can switch it back on the same way.

Click into the ssh user@host box and a list of recent connections drops down, newest first, with how long ago each one was used. Type a few letters to narrow it by name, host or user, then click one to open it. Only servers you have connected to at least once appear there. This is new, so it carries a Beta tag.

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.
• To rename a folder, click the pencil beside its name, or right-click the folder and choose Rename. The same menu opens every server in the folder side by side, or deletes the folder.
• 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.

Run after login (Beta) is a box on the session dialog. What you put there is typed into the shell once the prompt appears, one command per line, on every connect and reconnect: a cd into the directory you always start in, or tmux attach. It is stored in plain text on your machine, so keep passwords out of it. A tab restored at startup stays dormant, and nothing is typed into it until you press R.

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.

A tab you are not looking at shows a dot when something happens in it: blue for output, amber for a bell. It clears when you bring the tab forward. With Desktop notifications switched on in Settings, under Terminal, a bell, a session that ends and a connection error also raise a notification from your operating system. It names the tab and says what happened, never showing any terminal output, and clicking it brings SetuSSH forward on that tab. Both are Beta.

Right-click a tab for Rename, Duplicate, a colour to mark it with, Close and Close other tabs. A colour draws a strip along the top of the tab and is saved with the workspace, so it is still there after a restart.

To open a server straight into a split, press Ctrl+Shift+P and pick Split right with or Split down with, or drag a session from the sidebar onto the right or the bottom half of a terminal, or right-click it and choose Split right with this.

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.

Dragging a file from the list onto your desktop or a local folder copies it there (Beta). SetuSSH fetches the file first, so one over 64 MB is refused, and a transfer slow enough to outlast the drag lands in your Downloads folder instead, with a message saying where it went. Folders cannot be dragged out; use Download for those.

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.

A whole folder opens at once (Beta): hover its header in the sidebar and click the tiles button. Every server in it opens, the panes are tiled, and MultiExec is switched on, so one line typed reaches all of the ticked tiles.

Remote desktop

Remote Desktop (RDP) sessions live in the same list as your SSH servers, in the same folders, with favourites, tags and notes. This is new, so it carries a Beta tag.

To add one, press Ctrl+Shift+T or click New in the ribbon, and choose Remote Desktop at the top of the session dialog. Fill in the host, the port (3389 unless the server uses another), your username and, for a domain account, the domain. A saved password is kept encrypted on this computer, the same way an SSH password is.

Double-click the session to open it. The remote desktop opens in a SetuSSH tab, drawn by SetuSSH's own Remote Desktop client, so there is no other app to install on Windows, macOS or Linux. With no password saved, SetuSSH asks for one when you connect and does not keep it. If a saved password stops working, edit the session and enter the new one.

The desktop takes the size of the tab and follows it when you resize the window or hide the sidebar. It is drawn at your screen's full sharpness, even on a display scaled to 125% or 150%. A server that keeps a fixed screen size is shown scaled to fit the tab.

The bar above the desktop has Ctrl+Alt+Del, Win (the Windows key, which opens the Start menu on the remote machine), Full screen and Disconnect. While the desktop has the keyboard, keys go to the remote machine, SetuSSH's shortcuts included. Press Ctrl+Alt+Home, or click outside the desktop, to use them again; moving the pointer back over the desktop hands it the keyboard. Keys your computer keeps for itself, such as Alt+Tab, still act on your computer, so use the buttons to send Ctrl+Alt+Del and the Windows key.

In full screen the bar is hidden: move the pointer to the middle of the top edge of the screen to bring it back, or press Esc to leave full screen. To go full screen as soon as the desktop appears, tick Open full screen in the session. If connecting takes a while, the system may not allow it then; click Full screen instead.

While a remote desktop is connected, the clipboard is shared with it, as in other Remote Desktop apps: what you copy on your computer can be pasted there, and what you copy there can be pasted here.

The first time you connect to a server, SetuSSH shows its certificate and asks whether to trust it, as it does for an SSH server's host key. Most Remote Desktop servers use a certificate they made themselves, so this is expected. To check it on a Windows machine, run (Get-CimInstance -Namespace root/cimv2/TerminalServices -ClassName Win32_TSGeneralSetting).SSLCertificateSHA1Hash in PowerShell as an administrator. It shows the certificate in use; compare it with the SHA-1 line. A certificate issued for the server's name by an authority this computer trusts, such as your company's own, is accepted without asking. A server you reach by its IP address is always asked about.

If the certificate changes later, SetuSSH warns you before connecting. Windows renews its own Remote Desktop certificate from time to time, and a reinstalled server has a new one. Check the new SHA-1 on the server; if it matches, tick Replace the saved certificate for this server and click Accept anyway. Left unticked, you are asked again next time.

The server needs Network Level Authentication (NLA) or TLS turned on for Remote Desktop, as current Windows has by default. SetuSSH does not use the old RDP security layer, which is weakly encrypted and cannot prove which server you reached. Windows 7 and Windows Server 2008 R2 need update KB3080079 for the TLS version SetuSSH uses.

For a machine you can only reach from inside a network, set Go through an SSH server in the session dialog to one of your saved SSH servers. SetuSSH connects to that server and carries the remote desktop over it. The SSH server must allow port forwarding (AllowTcpForwarding, on by default), and it is the one that looks up the remote machine's name.

A remote desktop session counts towards the free plan's limit like any other saved session. Neither the AI assistant nor AI clients using AI access see remote desktop sessions.

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.

Updates

SetuSSH never installs anything by itself. When it starts it asks GitHub for the list of published releases and compares it with the build you are running. If a newer one is out you get a small window with what changed and a download button, and a badge in the bottom bar to open it again later. The answer is reused for 30 minutes.

Settings has an Updates page with the build you are running, a Check now button and a switch for the check at launch. The request carries the version you are running and nothing else, and it goes to GitHub, which is where the downloads live. Turn the switch off and the app makes no request of its own at all. The privacy policy sets this out in full.

On Ubuntu and Debian, installing from the apt repository means apt upgrade brings each new build in the usual way, as described under Install.

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.