Account → SSH gateway and Text UI

Connect with your own ssh, sftp, scp, WinSCP, FileZilla or similar client, pointed at your MisterShell hostname, instead of opening the browser. It is the same door: the same account, the same permissions, the same session policies, approvals and recording as opening a session from the browser. Nothing about a resource’s governance changes because you connected from a terminal — or from an automation tool such as Ansible, Netmiko, NAPALM or expect, which use the same door through a direct connection.

The default SSH port is 2222. Use the hostname and port supplied by your administrator; the examples below use shell.company.com:2222.

Your client never talks to a resource directly. It signs in to MisterShell, which then opens the session on your behalf — exactly what the browser’s Connect button does — and streams it back to your terminal.

Always use your MisterShell account’s email address as the SSH login name, for example alice@company.com. This applies to local, LDAP, and single sign-on accounts. Use the email address registered on your MisterShell account rather than a directory username.

For browser sign-in, approve the request while signed in to the account with that same email address. See Browser sign-in.

That plain login name lands you in the terminal (ssh) or the file catalog (sftp, scp). Appending a resource’s path to it — alice@company.com/emea/paris/core-rtr-01 — turns the login into a direct connection to that one resource, with nothing interactive in between.

A bookmark’s ssh_config entry hides the login name behind a plain Host alias (see Bookmarks), so day to day you rarely type it out. On the command line, ssh -p 2222 -l alice@company.com shell.company.com and ssh -p 2222 alice@company.com@shell.company.com are equivalent.

First connection — verify the host key

The first time any client connects to a MisterShell hostname it will ask you to confirm the server’s identity:

$ ssh -p 2222 alice@company.com@shell.company.com
The authenticity of host '[shell.company.com]:2222 ([203.0.113.10]:2222)' can't be established.
ED25519 key fingerprint is SHA256:Qk7…/Zw.
Are you sure you want to continue connecting (yes/no/[fingerprint])? SHA256:Qk7…/Zw

Before accepting the key, compare the fingerprint shown by your SSH client with the SSH bookmark menu in a resource’s Summary tab, on the Tags bar. If that menu is unavailable, ask your administrator for the fingerprint through a trusted channel.

The key is shared across your deployment, so every resource’s bookmark menu shows the same fingerprint. Once accepted, your SSH client remembers it and will warn loudly if it ever changes — see Settings for what a deliberate key rotation looks like.

Connecting directly to a resource

To land straight in a session on one resource — from a terminal or from an automation tool — put the resource’s path in the login name, right after your e-mail address:

<your e-mail>/<location path>/<resource name>[?credential=<vault entry name>]

$ ssh -p 2222 -l alice@company.com/emea/paris/core-rtr-01 shell.company.com
MisterShell — host key SHA256:Qk7…/Zw
Password: ********
core-rtr-01#

The device prompt is the first thing you see, and nothing is added around the session: no “Connecting …” line, no summary when it ends, no screen clearing. On the wire the connection behaves like SSH to the device itself, which is why tools written for plain SSH work without changes. The terminal and its dialogs are never shown on a direct connection — anything they would have asked is refused instead (see When a direct connection fails).

The path is the location path plus the resource name, exactly as the browse tree shows it, without the top-level root, matched without regard to case. A bare resource name (core-rtr-01) also works when it is unique among the resources you can see; if it is ambiguous, the connection is refused and you are told to use the full path.

Spaces and special characters

A / always separates path segments. Anything else that is awkward in a login name — a space first of all — is written percent-encoded: %20 for a space, so a resource core rtr 1 under emea/new york is alice@company.com/emea/new%20york/core%20rtr%201. A + is taken literally (it is not a space). The resource’s SSH bookmark menu encodes the login name for you, so copying from there is the easy way; ssh_config also accepts the unencoded form in quotes: User "alice@company.com/emea/new york/core rtr 1".

Signing in

Your personal SSH key. On a resource whose owner turned on Allow personal SSH keys for native SSH automation in the resource’s edit form, register the key under My SSH public keys and connect with it (ssh -i ~/.ssh/id_ed25519 …). The key alone signs you in — no password and no verification code. Your account must still be active and unlocked, the resource’s own credential is still required, and policy, recording and audit apply unchanged. A sign-in made this way can open sessions on that one resource and nothing else, and it stops working when you delete the key or its expiry date is reached.
Your password. The usual account password. A direct connection never asks for a verification code: an account that must present one is refused with a reason, unless it signs in with a personal SSH key (previous point). Directory (LDAP) and single sign-on accounts use a personal SSH key, with the account’s e-mail address as the login name.
Browser sign-in is not available on a direct connection: an empty password is refused rather than starting a browser approval.
Both the SSH password method and keyboard-interactive work, and keyboard-interactive has a single Password: prompt on a direct connection, so libraries that answer every prompt with the configured password succeed.

The resource’s credential

The resource’s own credential, or a credential template you have already filled in, is used automatically. When the resource needs you to pick a credential, name it in the login name: ?credential=<vault entry name>, matched without regard to case among the vault entries you may use, with %20 for spaces (?credential=netops%20rw). A direct connection never picks a vault entry on your behalf, even if only one fits — without ?credential= it is refused. When the resource does not need a credential from you, ?credential= is ignored.

From automation tools

# Ansible inventory (network_cli, netmiko, napalm — paramiko or libssh)
core-rtr-01:
  ansible_host: shell.company.com
  ansible_port: 2222
  ansible_user: alice@company.com/emea/paris/core-rtr-01
  ansible_ssh_private_key_file: ~/.ssh/id_ed25519   # a personal SSH key, on a resource that allows it
  # ansible_password: "{{ mistershell_password }}"  # the account password, when the resource does not allow a key (no MFA)

# Netmiko
ConnectHandler(host="shell.company.com", port=2222,
               username="alice@company.com/emea/new%20york/core%20rtr%201",
               key_file="~/.ssh/id_ed25519", use_keys=True)

With several keys loaded in an agent, set IdentitiesOnly yes (OpenSSH) or pass the key explicitly: each key your client offers counts as one sign-in attempt from your address.

$ ssh -T core-rtr-01 < commands.txt            # a bookmark alias; see Bookmarks

A terminal is not required: ssh -T and piped input are bridged as an 80×24 session. Closing your end of the input (the end of a piped file) does not end the session — output keeps flowing until the device closes the session, your client closes the connection, an error occurs or the session could not be reached in time. A piped script must therefore end with the device’s own exit command (exit, quit, \q, …); otherwise the connection idles until the device or the session’s idle timeout ends it. Window-size changes are forwarded while your input is open; once you have closed it they are not. Some command-line programs discard anything typed before they show their first prompt (database shells, for example): with those, send your commands once the prompt has appeared, as Netmiko and Ansible do.

What you see, and how it ends

Standard output carries the session’s bytes and nothing else.
Standard error carries MisterShell’s own messages, so they never mix with the device’s output: one MisterShell: <reason> line when the connection is refused after sign-in, [policy] command denied by rule "<name>" when a session policy blocks a command mid-session, Error: … if the session ends in error, and a timeout line if the session could not be reached.
The exit status is 0 when the session ended normally — you left the device shell, or you closed the connection — and 1 for any refusal or error. There are no finer codes.

When a direct connection fails

During sign-in — a wrong password, a verification code your account would need, an empty password, or a path that matches no resource you can see or several of them — the sign-in fails the way your SSH client already reports authentication failures, preceded by one MisterShell: <reason> line. OpenSSH prints that line; some libraries do not surface it. An unregistered or expired SSH key also fails as a plain SSH Permission denied (publickey…) authentication failure, but without a MisterShell: <reason> line — the gateway never accepts the connection. Only a registered key is different: the connection itself is accepted once the signature checks out, and only then can it be refused — on a resource that does not allow personal SSH keys, or an unknown or ambiguous path — closing with one MisterShell: Invalid credentials line and exit status 1.
After sign-in — the resource has no terminal session type (browser only), a credential is needed and none was named, no vault entry of that name fits, a session input has no default, a session policy denies the connection, access needs approval (retry once it is granted), or the platform reported an error — the connection is refused and closes; see What you see, and how it ends for how that is reported.

Take care with the path when you sign in with your SSH key: an unknown or ambiguous path, or a resource that does not allow personal SSH keys, is refused as a failed sign-in for your account — the same accounting as a wrong password. Repeated, it locks your account, and the lock applies to the web sign-in too.

Not available on a direct connection

sftp/scp with a resource path in the login name: the connection opens, but every file operation fails with permission denied. Use the plain login name for the file catalog, and the browser’s file manager to move files to or from a resource — see Files.
A command on the ssh command line (ssh … "show version") — see What is refused. Run commands inside the session, or send them through standard input as described above.

For the Text UI and file catalog, use your account password and, when required, the verification code from your authenticator app or e-mail. Complete any required MFA enrollment in the browser first. At an e-mail-code prompt, enter r to request another code; at an authenticator prompt, recovery:<code> uses a recovery code. Your client must support keyboard-interactive authentication for these prompts and browser sign-in.

You can sign in with a personal SSH key instead of your password (My SSH public keys). The Text UI always continues with a keyboard-interactive step after the key, even when your account needs no verification code — it completes that step automatically in that case, but a client with keyboard-interactive disabled cannot finish signing in with a key on the Text UI at all. When your account does require it, the verification code, or browser sign-in for directory and single sign-on accounts, follows there.

Leave the password prompt empty to sign in from the browser instead — the only option for single sign-on accounts, and available to anyone who would rather approve from a device they already trust. It is offered on the plain login name (the terminal and the file catalog), not on a direct connection:

$ ssh -p 2222 -l alice@company.com shell.company.com
MisterShell — host key SHA256:Qk7…/Zw
Password (leave empty to sign in with the browser):
Open  https://shell.company.com/app/device  and enter code  WXKT-9F2Q
Waiting for browser sign-in … ok (alice@company.com)

Open the link (or, from an already-signed-in browser, just go to /app/device), type the code, and approve. The approval page shows where the request came from and when — approve only codes you requested yourself, from a terminal you control. Codes are formatted XXXX-XXXX, are valid for five minutes, and can be used once.

Bookmarks

For resources with a Summary tab, the SSH bookmark menu on the Tags bar provides a copy-paste ssh_config block when native SSH access is enabled and the resource supports a shell session. Paste it into ~/.ssh/config. The copied alias is mistershell-resource-<id>; you can rename it to a memorable name such as the examples below.

The block puts the resource path in the login name, so the alias opens that resource directly. If a resource has no Summary tab, create an entry yourself using its location path and name:

# ~/.ssh/config
Host core-rtr-01
  Hostname shell.company.com
  Port 2222                    # omitted from the copied block when the port is 22
  User alice@company.com/emea/paris/core-rtr-01

Host fw-edge-01
  Hostname shell.company.com
  Port 2222
  User alice@company.com/emea/paris/fw-edge-01?credential=netops-rw

Host msh
  Hostname shell.company.com
  Port 2222
  User alice@company.com

$ ssh core-rtr-01          # straight into the session; prompts for the password only
$ ssh fw-edge-01           # same, with the named vault entry
$ ssh msh                  # the terminal, with every resource you may open
$ sftp msh                 # the file catalog

The menu copies one Host entry per resource; add a plain-login alias such as msh yourself for the terminal and the catalog.

The menu’s second line is the bare login name, ready to paste as ansible_user or a Netmiko username, and a caption reminds you to append ?credential=<vault entry name> when the resource needs your credential. Names are copied percent-encoded (%20 for a space, and likewise for characters such as ' or ( that ssh_config and Ansible inventory files would otherwise split on), so they paste unchanged into any of these files.

The terminal

Running ssh against your hostname with no resource path opens the full-screen Text UI (TUI), in the style of a terminal multiplexer, with every resource your roles let you open:

$ ssh msh
MisterShell — host key SHA256:Qk7…/Zw
Password: ********
Verification code: 482913

  1:core-rtr-01   2:db-prod*
┌ Resources ───────────┐┏ core-rtr-01 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┌ Session Assist ─────┐
│ Recent               │┃core-rtr-01# show ip int brief               ┃│ ● on                │
│   core-rtr-01        │┃Interface    IP-Address   Status   Protocol  ┃│ ◆ Gi0/1 went down 3 │
│   db-prod            │┃Gi0/1        10.0.0.1     down     down      ┃│   minutes ago; last │
│                      │┃core-rtr-01#                                 ┃│   change: shutdown  │
│ lab-linux-07         │┃                                             ┃│─────────────────────│
│ ▾ emea               │┃                                             ┃│ › what changed?     │
│   ▾ paris            │┃                                             ┃│                     │
│     core-rtr-01      │┃                                             ┃│                     │
│     db-prod          │┃                                             ┃│                     │
│     ops-jump  (rdp)  │┃                                             ┃│                     │
└──────────────────────┘┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛└─────────────────────┘
 C-b c new  n/p tabs  x close  t hide tree  a end assist  [ scroll  ? keys  d quit

The top line lists your open sessions as tabs, 1:core-rtr-01, 2:db-prod; the active one is highlighted, and a * marks a tab whose Session Assist has something new for you. A session that ends disappears from it at once.
Resources, on the left, is the same tree the browser’s browse page shows you: your recent sessions first, then the locations. Entries you cannot open from a terminal — graphical types such as remote desktop, VNC or a web application, or resources outside the locations where you may open sessions — are dimmed and skipped by the selection.
The centre is the active session, or — while the tree has the focus — a summary of the selected resource or location.
Session Assist, on the right, appears only when you turn it on for the active session; it takes no space otherwise.
The bottom line always shows the keys that apply right now; nothing else on the screen is a key hint. The pane with the heavy border is the one your keys go to.

The prefix key

When the session pane has focus, the keys you press go to the device, with one exception: Ctrl-B — written C-b on screen — is the prefix for the terminal’s own commands, as in tmux. Press it, release it, then press the command key. C-b ? shows the full list at any time:

Keys	What they do
`C-b c`	open the tree and connect
`C-b n` / `C-b p`	next / previous tab
`C-b 1` … `C-b 9`	n-th tab
`C-b x`	close the active tab (asks first if the session is live)
`C-b T`	toggle the interface between light and dark
`C-b t`	show or hide the tree
`C-b a`	start Session Assist, or end it and close the pane
`C-b +` / `C-b -`	widen / narrow the focused tree or Assist pane
`C-b Tab`	cycle focus: session › tree › assist
`C-b Esc`	back to the session
`C-b [`	scroll / copy mode
`C-b r`	refresh the tree, permissions, and Shell Profiles
`C-b ?`	this list
`C-b d`	close every tab and quit (always asks for confirmation)
`C-b C-b`	send a literal `Ctrl-B` to the device

While the session pane has focus, Ctrl-C, Ctrl-D and Ctrl-Z keep their normal meanings on the device. The tree, Assist pane and dialogs handle keys themselves when they have focus.

Multiple shells on the same resource

Each connection opens a new shell session. You can open several tabs for the same resource; they remain independent. Your native SSH and browser shells share a limit of three live shell sessions per user and resource by default. If that limit is reached, close one of your existing shells before opening another. A new native connection does not resume an existing shell.

The Text UI also has a separate limit of eight open tabs per SSH connection by default, across all resources. Your administrator can change both limits under Advanced Settings.

The tree

When the tree has the focus, ↑/↓ move; Enter on a location expands or collapses it, → expands, ← collapses or goes up to the parent; Home/End and PgUp/PgDn jump. Type to filter: every letter, digit or punctuation key narrows the list to the resources whose name contains what you typed (Backspace erases, Esc clears), so a name can always be typed or pasted in full. Selecting a resource shows its summary in the centre — type, location, address, status and health with the last check, verification results, tags, and the actions you have on it; selecting a location shows its path and four health cards: Healthy, Degraded, Critical, and Unknown, counting the resources below it. Resource summaries place a Resource Info card (including available snapshot facts such as hostname, OS, and uptime) beside the enabled health metrics from the latest snapshot, with status colours and percentage bars.

A second row shows the latest Note, when one exists and your account has app.notes.read for that scope. This row stays visible even when resource information is long. Markdown headings, emphasis, lists, code, links, and tables are rendered as terminal text. Scroll the cards or Note independently with the mouse wheel over that row, or use Shift+PgUp / Shift+PgDn while browsing the tree (keyboard paging moves into the Note after the cards). Reselect the node or use C-b r to load note edits made in the web UI. Large notes show their first 64,000 characters with a truncation notice; the complete note remains available in the web UI. Tables whose padded layout would be too large are shown as plain Markdown text.

Enter on a resource connects: the session opens in a new tab and the keys go to it. → or Space on a resource lists its Connect action instead. Esc (once any filter is cleared), or C-b Esc, returns to the session that was showing. When the tree is hidden, C-b c brings it back with the focus on it; C-b r refreshes it after a resource was added or moved.

The Recent group is your own session history and only appears if your roles include the session history permission. Resources with a bound credential open without any question; when a resource needs a credential from you, a dialog lists your vault entries that fit plus enter a username and password now. A session that needs an approval offers to retry once it is granted; anything the platform refuses is shown as a message and the tab is not opened. The session type and any per-type input a session needs are taken from the resource’s own defaults, exactly as the browser’s Connect button uses them — you are only asked for a value the resource declares required and has no default for.

When the tab limit is reached, a dialog asks you to close a tab first.

Sessions and tabs

Commands you type inside a session are governed exactly as in the browser: a command your session policy denies shows the policy’s message — [policy] command denied by rule "<name>" — as a one-line banner over the bottom of the session, gone at your next keypress, and is never sent to the device; a command that needs approval holds until a reviewer decides; an error or a timeout is reported the same way. The device’s own output is never touched: it is what you see in the centre and what the recording contains.

When a session ends — you left the device shell, you closed the tab with C-b x or its top-right [X] button, or the connection to the device was lost — its tab disappears and the bottom line reports it (core-rtr-01 ended · 12m41s · closed) until your next keypress; the neighbouring tab becomes active. With no tab left, the tree takes the focus so you can open the next resource without signing in again. C-b d opens a Yes / No / Cancel confirmation, even with no sessions open. Yes ends all sessions and enabled Assist chats, then closes the connection with exit status 0. No, Cancel or Esc keeps the TUI open.

C-b [ scrolls back through the session’s history — ↑/↓, PgUp/PgDn, g/G (or Home/End) for the oldest line and the live screen; / searches upwards from the bottom and n/N step through the matches (a match in the history is shown as the top line). q or Esc leaves. Drag across the visible session content to select it, then release to send it to your clipboard. This also works in the scrolled-back view. Scrollback in the SSH terminal is capped at 768 lines per tab at the default eight-tab limit, or 192 lines with a 32-tab limit, whatever the profile says. The display is capped at 1024 columns and 128 rows with eight tabs (32 rows with a 32-tab limit). Sessions in background tabs keep running and keep their history while you look elsewhere.

Session Assist

On a deployment where AI Session Assist is configured and your roles allow you to use AI, C-b a opens the Session Assist pane for the active session and starts its chat immediately. It is the same assistant the browser’s session page offers: it follows the session, comments on its own when something worth noting happens (◆ lines — a tab in the background gets a * in the top line when one arrives), and answers what you type in the entry block below the rule (Enter sends, Alt+Enter starts a new line). Answers and proactive notes render Markdown as they stream, including headings, emphasis, lists, links, tables and code blocks. Code keeps its indentation; long lines wrap to the pane. Images show their description and URL as text. The tools it uses show as one dim line each, with no blank rows between adjacent tool calls. While it is starting or answering, the entry box says thinking and ignores typing, pasting and sending; you can still scroll the transcript or leave the pane. Your draft and submitted messages use blue text, distinct from assistant replies in both light and dark interface themes. Accepted questions stay in the recent transcript. A refused question appears with its reason while any answer already being generated continues. Older transcript entries eventually leave the pane; the full conversation is available in the browser while Assist is active. Entry editing appends at the end, with Backspace to remove characters.

The pane is the assistant’s on state: while it is shown for a session where it is on, the bottom line reads a end assist, and C-b a ends the conversation for that tab (the pane closes). Clicking the Assist pane’s top-right [X] does the same. The session pane’s [X] asks for confirmation before closing that session and its Assist chat. Confirmation dialogs include Yes, No, and Cancel buttons: click one, or use Tab / Shift+Tab or arrow keys to select it and Enter to activate it. Y, N, and Esc are direct shortcuts. Local close/quit dialogs start on No; both No and Cancel keep the session open. The assistant is per session and ends with it. Ending Assist deletes that chat. Quitting the TUI closes all open sessions and their Assist chats, including chats that are still starting. On a deployment without AI Session Assist, or without the permission, the pane and its hints do not exist. Command injection by the assistant remains a reviewed, audited platform action — the terminal never types into a session on the assistant’s behalf.

If stopping Assist fails, the pane returns with an error; use C-b a or [X] to retry. Sending and starting another chat may be blocked until the previous chat has stopped. If the connection to MisterShell remains unavailable, closing the terminal does not confirm that the assistant has stopped. Check its status in the browser.

Colours and Shell Profiles

The interface has its own dark and light colour schemes. Click C-b T light or C-b T dark at the right of the bottom bar, or press C-b T (uppercase T), to switch. The choice lasts for the current SSH connection and starts in dark mode. It applies to bars, borders, the tree, summaries, dialogs and Session Assist. Switching tabs leaves the interface unchanged.

Each session’s terminal content follows your Shell Profiles, the same way the browser does: the profile mapped to its resource type, else your default profile, else the system default. The interface toggle does not change session colours. Profiles control the background, foreground, sixteen ANSI colours, selection colours, cursor colour/style/blink (as your terminal honours it) and scrollback depth (up to the terminal’s cap, above).

After editing profiles or mappings in the web UI, press C-b r to apply colours and cursor preferences to open sessions without reconnecting them. Their content and history remain intact; scrollback changes apply to newly opened sessions. Font family, size, weight, line height and letter spacing remain properties of your terminal program.

Colours are shown exactly when your terminal announces 24-bit colour: a terminal type (TERM) such as xterm-kitty, wezterm, alacritty, foot, ghostty or a -direct variant, or COLORTERM=truecolor (or 24bit) forwarded by your SSH client — OpenSSH forwards TERM always but COLORTERM only when asked: add SendEnv COLORTERM to the bookmark’s Host entry, or pass -o SendEnv=COLORTERM. Other terminals get the nearest of their 256 colours, so a profile’s tints are approximations there.

Mouse and panel widths

In terminals that support mouse reporting, click a pane to focus it or a tab name to switch sessions. Click a location to expand or collapse it; click a resource to select and preview it. Right-click a resource to open its actions, then click an action to run it. The wheel scrolls the tree or Assist transcript. The bottom-bar action hints are clickable too: clicking a assist starts Assist, and clicking d quit opens the same confirmation as the keyboard. The confirmation’s y yes / n no hints are clickable. For a paired hint such as n/p tabs or +/- width, click the individual key to choose its direction; clicking the label runs the first action. Blank space, status notices and typing instructions do not trigger commands.

Drag the tree’s right border or Assist’s left border to adjust its width. C-b + and C-b - change the focused side pane by two columns. Docked panes keep at least 40 columns for the session; widths persist while you switch tabs or resize the terminal.

Left-drag inside the session to select text; releasing automatically sends a clipboard request using OSC 52. The highlighted viewport stays still while you drag, while the session continues running. Only session text is copied, without pane borders, banners or ANSI styling. Wrapped lines join; explicit line breaks and indentation are preserved. Selection uses the session’s Shell Profile colours. A click without dragging does not copy.

Clipboard access must be allowed by your terminal (and any intervening tmux or screen). The notice Copy request sent confirms delivery to the terminal, not acceptance by the clipboard. If it is blocked, use your terminal’s native selection bypass, commonly Shift-drag. Selection is limited to the displayed viewport and 64 KiB of UTF-8 text per copy; larger selections are rejected without truncation. Scroll with C-b [ before selecting older output; dragging does not auto-scroll. Esc, keyboard input, switching tabs, opening a dialog or resizing cancels a drag. The wheel is ignored during a drag.

Small windows

The session area keeps at least 40 columns by 10 rows. When the window is too narrow or too short for that, the Session Assist pane folds away first, then the tree; both come back when there is room again, and until then C-b t / C-b a still open them, laid over the session. If the window cannot fit a 60-column by 15-row content area (62 columns by 19 rows including borders and bars), it shows terminal too small — enlarge the window; dialogs and the key list are still shown whatever the size, so a question is never invisible. Every resize is passed on to the device as the size of the session area, as the browser does.

When the terminal is unavailable

The plain login needs a terminal (ssh -t, or no -T) — see What is refused. Two further lines can appear on standard error, with exit status 1:

MisterShell: the interactive terminal is unavailable on this Core. — the Text UI is unavailable; tell your administrator. Direct connections and the file catalog are unaffected.
MisterShell: the interactive terminal ended unexpectedly. — the terminal stopped mid-way; every session it had open is ended cleanly, exactly as if you had quit. Reconnect and open them again.

Connection limits and stalled clients

If your SSH client reuses one connection for several shells or file transfers, it can open at most four SSH channels at once. TUI tabs share one channel and have their own tab limit. The gateway also applies an overall connection limit set by your administrator. If you see MisterShell: SSH channel limit reached., close an unused shell or file transfer and wait for it to finish closing before retrying.

An unresponsive client can be disconnected, ending the sessions in that connection. Reconnect and open new sessions after resolving the client or network problem.

Files

Catalog access — `sftp`, `scp`, WinSCP, …

Your SFTP client sees the MisterShell file catalog, scoped exactly like the browser’s Files page: paths look like /<location path>/<catalog folders>/<file>. The catalog is the only way files enter or leave the platform — SFTP never touches a resource’s own filesystem directly.

$ sftp -P 2222 -o User=alice@company.com shell.company.com
Password: ********
Verification code: 482913
sftp> ls /emea/paris
firmware/  configs/  running-config-core-rtr-01-2026-09-17.bak
sftp> put cat9k_iosxe.17.15.01.SPA.bin /emea/paris/firmware/
Uploading … 100%
sftp> get /emea/paris/running-config-core-rtr-01-2026-09-17.bak
Fetching … 100%

$ scp ./startup.cfg msh:emea/paris/configs/
$ scp msh:emea/paris/configs/startup.cfg .
$ sftp msh:emea/paris/firmware/               # your ssh_config alias works for sftp too

OpenSSH 9.0 and later speaks SFTP for scp by default, so the examples above work unchanged; older scp clients should use sftp instead (see What is refused). WinSCP, FileZilla, Cyberduck, and editor SFTP plugins all work the same way — protocol SFTP, your hostname, port 2222 (unless your administrator uses another port), your plain login name (no resource path), and your password plus verification code at the prompt.

Listing, upload, download, creating a folder, renaming and deleting are supported, under the same size limit and access rights as the browser Files page. A few operations the catalog does not support: uploading onto a name that already exists (delete or rename the existing entry first — the catalog never silently overwrites), moving an entry between locations, and symlinks, permissions or timestamps.

Moving files to and from a resource

Copying a file between the catalog and a resource is always a governed transfer — the same feature, rules, approvals and log as the browser file manager. That transfer is started from the browser’s file manager; the Text UI does not offer resource file transfers, and sftp/scp with a resource path in the login name is refused (see Not available on a direct connection). Upload to the catalog over sftp, then move the file to the resource from the browser — or the other way round.

What is refused, and why

Native SSH access refuses port forwarding, commands passed on the SSH command line, and unsupported file-transfer protocols. Sessions remain subject to MisterShell’s permissions and policies:

$ ssh msh "show version"
MisterShell: commands are not accepted here; connect with the login name <email>/<location>/<resource> and run commands inside the session.

$ ssh msh < script.txt
MisterShell: a terminal is required (use ssh -t).

$ rsync -av ./dir msh:emea/paris/srv-01/home/
MisterShell: rsync/legacy scp are not supported; use sftp or scp (OpenSSH ≥ 9.0).

The first two apply to the plain login name: the full-screen terminal needs a real terminal to draw on (do not pass -T or pipe its input), and it accepts no command. A direct connection needs no terminal and takes its input from a pipe, but refuses a command on the command line the same way.

A local port forward (-L) is refused too, but not at login — the session opens normally, and the refusal shows up only when something actually connects to the forwarded port:

$ ssh -L 8443:10.0.0.5:443 core-rtr-01
… (the session opens normally)
channel 3: open failed: administratively prohibited: MisterShell: port forwarding is not permitted through this gateway.

A remote port forward (-R) is refused the same way; your client reports it locally rather than printing MisterShell’s message, for example:

Warning: remote port forwarding failed for listen port 8443

Both attempts are recorded in the security log even though only -L’s refusal names MisterShell on screen. Agent forwarding (-A) and X11 forwarding (-X) are silently ignored rather than refused; jumping through the gateway with -J fails the same way a local forward does, since it also tries to open a direct connection to another host. If your connection drops for any reason, the session it was carrying ends — there is no reconnect to an in-progress session from a terminal client.

Permissions

Connect to a resource: the same permission the resource’s Connect button needs — app.resources.execute, at the resource’s location. The tree offers Connect only where you have it.
See a resource’s summary in the tree: app.resources.read (the tree itself already implies it); the Recent group: the session history permission.
Read resource or location notes: app.notes.read at that location.
Session Assist: the permission to use AI (app.ai.execute), plus a configured Session Assist agent on the deployment.
Sign in to a resource with a personal SSH key alone: no permission of your own; the resource must allow it (Allow personal SSH keys for native SSH automation in its edit form, set by whoever can edit the resource — app.resources.write).
Browse, upload or download in the catalog: app.files.read / app.files.write; delete: app.files.delete — at the location the path falls under.
Approve a browser sign-in for an account: being signed in to the browser as that same account. There is no separate permission — the approval is identity-matched, not role-gated.

Settings

Whether the door is open, the port it listens on, connection limits, the number of tabs a terminal may have open, and the host key are configured by an administrator under Advanced Settings. The per-resource Allow personal SSH keys for native SSH automation toggle is described there too.