SSH hosts and SFTP

The host manager is where you save, edit, import and connect to hosts. Open it in any of these ways:

• In the SSH section of the left sidebar, click the sliders button (tooltip Manage SSH & SFTP servers). The + button beside it opens the manager on a blank New Host form.
• Press Cmd+Shift+H on macOS or Ctrl+Shift+H on Linux. Windows uses the same shortcut in the code, but it has not been tested there. You can change the shortcut in Settings.
• Choose SSH & SFTP Session Manager in the command palette.

The left column lists Saved Sessions, with a filter chip for each group. The right column is the form for a new host or the one you selected. Esc, or a click on the dark area outside the window, closes the manager. The SSH section of the left sidebar also lists every saved host: click one to open it in a new tab, the same as Connect. Adding, editing and deleting hosts is done in the manager. Other shortcuts are in Keyboard shortcuts.

1. Open the host manager and click New Host.
2. Fill in the fields below. Bookmark Name, IP Address / Domain and Username are required.
3. Pick a method under AUTHENTICATION METHOD.
4. Click Save SSH Session.

To change a host, click its card, edit the form and click Update SSH Session. The trash icon on a card deletes the host after you confirm. If you typed a new password and the system keychain refuses it, nothing is changed: the form stays as it is and shows Could not save the password to the keychain, so nothing was changed, followed by the reason.

Import reads a file you pick. It does not read ~/.ssh/config by itself.

1. In the host manager, click Import above the host list.
2. Pick an OpenSSH config file, a MobaXterm sessions file, an iTerm2 profile export or a JSON file. The picker accepts .config, .mxtsessions, .json, .txt and .ini files.
3. Open each imported host and fix what the import did not bring across (see the note below).

OpenSSH's config file has no extension and sits in a hidden folder. The easiest route is to copy it first, for example cp ~/.ssh/config ~/Desktop/ssh-config.txt, and import the copy.

Session Manager Pro can bring iTerm2 profiles in as Saved Sessions and SSH hosts. Open it from the command palette or with Cmd+Shift+O on macOS (Ctrl+Shift+O on Linux), and click the Import / Export tab.

On macOS, click Find profiles on this Mac. The app reads iTerm2's preferences file with plutil, or the file in iTerm2's custom preferences folder when iTerm2 is set to load from one. That button is macOS only. On any system you can instead click the file area of that tab to pick iTerm2's JSON export, or paste its text into the JSON box, and click Import Session. Either way you get the same list to pick from.

Nothing is written until you click Import selected (N), where N is the number ticked. A skipped profile cannot be ticked. Select all and Select none change the ticks. Importing a profile again updates its Saved Session instead of adding a second one. A host with the same user@host:port as a saved host is skipped, and the result line counts it.

1. Open the host manager.
2. Optional: click Ping on the host's card. It only checks that the address and port accept a TCP connection from your machine. It does not log in and does not go through the jump host.
3. Click Connect. A new tab named [SSH] <name> (<address>) opens.
4. Answer the prompts from ssh in the terminal, such as confirming the host key the first time, and your password, passphrase or code.

The pane runs ssh itself, the one already installed on your computer: MXterm has no SSH library of its own, and the file panel runs ssh and scp too. On Windows that means the OpenSSH client, which has not been tested there. There is no local shell underneath it and no command line typed into one: the app builds the arguments from the fields you saved and hands them straight to ssh, which then behaves as it does in any terminal. MXterm adds these options:

• -o ControlMaster=auto -o ControlPath=~/.mxterm/sockets/%r@%h:%p -o ControlPersist=10m: one shared connection per host, which the file panel, the stats strip and port forwarding reuse. It stays open in the background for 10 minutes after nothing is using it.
• -o ServerAliveInterval=30 -o ServerAliveCountMax=3: keepalive probes, so a dropped connection is noticed in about 90 seconds rather than the next time you type.
• -i, -J, -A and -p from the host's key file, jump host, agent forwarding and port. -i is passed only for a key-file host.
• -- before the destination, so a host or user name that begins with - can never be read as an option.

Each field is checked before the connection is attempted: host, user and jump host by the rules OpenSSH itself applies, and the port, key file path and working directory for values that cannot be passed safely. If one is refused, Connect opens no tab and the manager shows a message naming the field and the reason. A saved tab that is refused when it starts shows the same message in a bar at the top of the pane.

If the host has no Default Working Directory and you selected Custom Directory Path under Default SSH Working Directory in Settings → Terminal, the tab starts in that directory. See Settings.

Every pane, the file panel, the stats strip and port forwarding of one host share a single background ssh connection. It logged in once and keeps the state it had then. If the server's password had expired at that moment, the file panel can keep failing after you change the password in the terminal, because it still uses the old connection.

Reset connection closes it, so the next one logs in from scratch. The file panel's error card shows the button when the failure is an expired password or a refused login. Click it: the app closes the connection and opens a new SSH tab to the host. Log in there, then click Retry. If the tab cannot be opened, the panel tells you to open one yourself. Every session through the old connection ends with it, including panes and running port forwards.

The app also closes the shared connection by itself when:

• you save an edit to a host that changes its address, port, user, authentication method, key file, jump host or agent forwarding, or that saves a new password;
• you delete a host or remove its saved password;
• you add a host and a connection to that address is still open.

Renaming a host, or changing its group or working directory, leaves it open. Editing, deleting or adding a host, or saving or removing a password, also leaves it open when another saved host has the same user@host:port. In that case use Reset connection if the connection has gone stale.

Every SSH tab has a file panel for its host, on the left by default. The buttons in the panel header open port forwarding, move the panel to the other side, turn Follow terminal folder on or off, refresh the folder, show or hide hidden files, and hide the panel. When the panel is hidden, click the FILES (SFTP) strip to bring it back. Drag the panel's edge to resize it. It opens at about 30% of the workspace width, never below 420 px or above 640 px, and the width you drag it to is remembered. The dropdown in the header switches the panel and the stats strip to another saved host; the terminal stays where it is.

The file panel is one view of the server's files. It has no local half, so it is not a dual-pane manager, and it does not sync or mirror folders between your computer and the server: files move only when you upload or download them. Your own files are in the Explorer tab (see Editing a file on your own machine).

The panel opens in the home directory of the account you log in as, which it asks the server for. The home button returns there; its tooltip still reads Go to Root (/root), whatever the account. To go somewhere else, click the path bar, type an absolute path such as /var/www and press Enter. Click a segment of the path to jump back up.

Type in Quick file filter... to filter by name, or use the All, Folders, Code, Images and Archives chips. Click the File Name, Size or Modified header to sort. The search button next to the filter opens Remote Grep Search: it searches the text inside files under the current folder, skips .git, node_modules, vendor, storage, dist, build and .cache, lists up to 60 matching lines, and opens a file in the editor when you click a result.

A link whose target is missing is still listed. The listing uses python3 on the server when it has it and falls back to ls -la otherwise. With ls -la, a name with several spaces in a row can show with fewer, and a link shows as name -> target.

Keys work after you click inside the panel:

Upload File and Upload Folder… in the toolbar, and Upload files in the right-click menu, copy one file or folder from your computer into the current folder. You can also drag files from Finder onto the panel, which uploads them to the folder you are looking at. A drop onto an SSH pane uploads too (see Drop files on an SSH pane), and a drop onto a local pane still types the local paths. Download File in the right-click menu, or the download button on a file row, saves it to your Downloads folder. Folders can be uploaded but not downloaded, and there is no dragging out of the panel to download. Progress shows in Transfer Queue at the bottom of the panel.

When you cd in an SSH terminal, the file panel can move to the same folder. Following is on by default. The Follow terminal folder button in the panel header turns it off and on, and the panel remembers your choice. A green dot on the button means the terminal is reporting its folder.

The folder comes from the server's shell, which has to report it with the OSC 7 escape sequence. fish does this by itself. bash and zsh need one line in ~/.bashrc or ~/.zshrc on the server. MXterm never types anything into your SSH session to make it report.

If nothing has been reported about 8 seconds after the terminal's first output, the panel shows a hint with Copy for bash (~/.bashrc) and Copy for zsh (~/.zshrc) buttons that copy that line. Add it to the startup file on the server and open a new terminal. Don't show again for this server hides the hint for that host.

• While the panel is open, it follows an SSH pane of the same tab that runs the host it shows: the focused one once it has reported a folder, otherwise the one that reported last. A local pane is never followed.
• It moves only when the terminal's folder changes. The same folder reported again at every prompt does not pull the panel back from a folder you opened yourself.
• It does not move while you type in the path bar. It waits for the next report.
• If you cd several times in quick succession, the panel lists only the last folder.

Drag files or folders from Finder onto an SSH pane. MXterm uploads them to a folder on the server and types their server paths at the prompt, so you can use them in the command you are writing. The file panel does not need to be open. A drop onto the panel uploads into the folder it shows, and a drop onto a local pane types the local paths.

• The folder is the one the terminal reported (see above), else the one the file panel of that tab shows, else your home folder on the server. A drop never uploads into / unless the terminal reported /. It uploads nothing and tells you to cd into a folder first.
• A name that already exists is never overwritten. The upload is named name (1).ext, name (2).ext and so on, and the path typed is the new one.
• The paths are typed after the last upload finishes, separated by spaces, with a space at the end. A name that needs it is put in single quotes. Only files that uploaded are typed, and only in that pane, even with broadcast on. A name with a single quote, a backslash, ! or a control character is uploaded but not typed, and the notice lists it.
• The uploads appear in Transfer Queue. If the folder cannot be read, nothing is uploaded and the notice gives the reason. Only one drop per host runs at a time, so a second says to drop again when the first finishes.

A bar at the bottom of the pane shows progress and the result. A clean result disappears after 6 seconds. A failure or a refusal stays until you close it.

Double-click a text file, press Space on it, or right-click → View/Edit. The editor has syntax highlighting, a theme picker, a font size picker and word wrap, and it remembers those choices. Only UTF-8 text opens; download other files instead.

The editor shows the file as it is on the server, and a save writes it back with the same final newline: a file that has no final newline, such as authorized_keys, still has none afterwards, and a file that has one keeps it.

A save first checks whether the file changed on the server since you opened or last saved it, for example through a deploy. If it did, This file changed on the server offers Cancel, Reload from server (drops your edits and loads the server's version) and Overwrite anyway. The check uses python3 on the server; without it, the save goes ahead unchecked.

The save writes to a temporary file next to the original and then copies it over, so a dropped connection does not leave the file empty, and the file keeps its permissions and owner.

The same editor now opens local files too. The right panel's Explorer tab shows a tree of the folder the focused pane is working in (your machine, not a server), and clicking a file opens it in the editor you just read about. There is no host to pick and no connection involved.

• Open the right panel with Cmd+Option+B on macOS or Ctrl+Alt+B on Linux, and choose the Explorer tab (the folder-tree icon).
• The tree is rooted at the focused pane's working directory, and re-roots itself when you focus a pane working somewhere else.
• Filter by name, show or hide hidden files, and refresh with the buttons at the top.
• Click a file to edit it. Cmd+S (Ctrl+S on Linux) saves it back to disk.

Only files the SFTP panel would already let you edit can be opened here: UTF-8 text up to 5 MB. Anything else is left alone.

Port forwarding lets you reach a port that listens on the server's own 127.0.0.1, such as a database, from your machine. The forward is added to the tab's shared SSH connection.

1. Connect to the host and log in in the terminal.
2. In the file panel header, click the port forwarding button (SSH Port Forwarding & Tunnels Manager).
3. Under Add New Port Forward, enter a name, a local port and a remote port, then click Add Rule.
4. Click Start on the rule. It shows RUNNING once ssh has accepted the forward.
5. Point your client at 127.0.0.1 and the local port. Stop removes the forward.

Each rule is ssh -L 127.0.0.1:<local port>:127.0.0.1:<remote port>. The local port listens only on your machine's loopback, and the far end is 127.0.0.1 as seen from the server. This dialog cannot forward to another machine on the server's network, open a port on the server (-R), or start a SOCKS proxy (-D).

If Start shows an error mentioning Control socket, there is no open connection for this host yet. Log in in the terminal tab and try again.

A strip at the foot of an SSH tab shows the host name, uptime and three readings:

A reading is green up to 65%, amber above 65% and red above 85%. The strip refreshes every 20 seconds, and Refresh VPS stats reads it now. It runs a short python3 script over the shared connection and reads Linux /proc files, so it needs python3 on the server, and on a password host it needs the terminal to have logged in. The strip appears after the first successful read; without python3 it does not appear.

Command Recipes matches what you type against a fixed set of ready-made Linux commands: large files, memory and CPU use, disk usage, open ports, Docker, Nginx, UFW, system logs and reboot. No AI model runs. Open it with the round button at the bottom right of an SSH tab, or with Cmd+J on macOS.

Type a request or click a quick tip. When a recipe matches, you see the command and a one-line explanation. Copy copies it. Insert & Run In Terminal types it into the focused pane of the current tab, presses Enter and also copies it. When nothing matches, no command is offered.