Connect over SSH
Open an SSH terminal on another machine through one of your Subshell nodes.
Before you start
You need launch access to an online node and an SSH account on the destination. The connecting node must be able to reach the destination over the network. Your browser doesn't need that network access, and the destination doesn't need Subshell installed.
For example, you could open the dashboard on your phone, connect from a node in your office, and sign in to a build machine that only the office network can reach.
Open the connection form
- In the server dashboard's sidebar, choose Workspaces, find the Subshells section, open the ⋯ menu beside the grouping dropdown, and choose Add subshell. If a workspace is open, select New subshell in the dialog.
- Select SSH terminal.
- Under Connect from, choose the node that will make the SSH connection.
- Under SSH destination, enter an address such as
developer@build.example.com:22, or choose a suggestion. SSH aliases come from the connecting node's SSH configuration; their suggestions show the resolved username, host, and port when available. - To reuse these choices, select Save as preset and enter a Preset name. Subshell saves the preset before trying the connection.
To fill the form from an existing preset, choose it under SSH preset. Review its connection details before starting; selecting a preset doesn't connect.
If outgoing SSH is disabled on a node you own, the gold notice explains that starting the subshell will enable it. For someone else's node, its owner must enable SSH first. The form names the owner when available and checks every five seconds while you wait. An administrator manages this setting for the built-in node on the server host.
Choose how to sign in
Under Authentication, choose keys on a node, a key on your own machine, or a password.
| Choice | What happens |
|---|---|
| Use the connecting node’s keys | SSH uses the connecting node's SSH configuration and available keys. The node's name appears below the option. |
| Use another node’s keys | Choose a second node under Use keys from, then select the keys this connection may use. You need launch access to both nodes. |
| Use a key from my machine | Choose a private key on your machine. Your browser or desktop app signs one login without uploading the key. |
| Enter a password when connecting | Enter the destination account's password in the terminal when SSH prompts. Subshell doesn't save it. The destination must allow password authentication. |
When using another node's keys, those keys must be loaded in an SSH agent that the node's Subshell process can access. Keys available in an interactive terminal might not be available to a background service. If the list is empty or unavailable, ask that node's owner to check its SSH agent and the service's SSH_AUTH_SOCK environment, then select Reload keys. See Files and paths for the node's configuration locations.
The private keys stay with the node supplying them. Subshell relays encrypted signing requests between the two nodes for the keys you selected. Both nodes must remain available for authentication. If SSH is disabled on a key source you own, the form explains that starting will enable it; you'll then select keys before connecting.
Use a key from your machine
Select Use a key from my machine to see the key controls and security information. Choose an OpenSSH-format Ed25519, ECDSA, or RSA private key.
Keep the browser page or desktop app open until authentication finishes. The connecting node and destination must support OpenSSH host-bound authentication. Jump hosts and host-key aliases aren't supported for this option. A remote server must use HTTPS; local loopback HTTP is allowed.
In a browser
Trust the website before choosing a key
Subshell does not upload or save your SSH key or passphrase. Compromised page code could still steal them, so only continue if you trust this website and its operator. Complete erasure from browser memory cannot be guaranteed.
- Read the warning and select I trust this website and its operator.
- Select Choose key… and browse to your private key. If your
.sshfolder is hidden, follow the operating-system tip beneath the button to show hidden files in the file dialog. - If the key is encrypted, enter its passphrase under Key passphrase (if encrypted).
- Select Start SSH subshell. In Use this key to connect?, check Connecting node, Key file, and SSH command. The command shows the destination account and host, with
-pfor a port other than 22. - Compare Host fingerprint with one obtained from the destination's administrator through a trusted channel. The named connecting node supplied the fingerprint; it isn't independent proof of the destination's identity. Select Use key and connect when you've verified it.
Subshell reads the selected file after you approve the destination and signs one authentication, with a 90-second limit. It then releases the temporary signing copy of your key from browser memory. Cancellation, errors, and expiry also release that copy.
If an attempt fails or you cancel the destination confirmation, the form keeps the selected file and passphrase so you can correct the problem and retry. Changing the destination before starting also keeps them; the next attempt asks you to approve that destination. The passphrase remains in the browser's password field until the signing flow succeeds, you leave the form, or you switch authentication methods. Choosing another key clears the passphrase too.
In a desktop app
The desktop picker supports Ed25519, ECDSA, and 2,048–8,192-bit RSA private and host keys. RSA authentication uses SHA-256 or SHA-512; SHA-1 is refused.
In an updated Subshell desktop app, select Start SSH subshell to open the native destination confirmation and file picker, which starts in your home directory's .ssh folder. Encrypted keys ask for their passphrase in a separate native app window. The private key and passphrase stay outside the dashboard page, server, and connecting node. The native signer also releases its key after one authentication attempt or within 90 seconds; this isn't a guarantee of physical memory erasure by the operating system.
If a connection with your key fails
Read the reason shown under Connection failed or Connection needs attention in the form. If SSH ends before requesting a signature, check that the selected key is authorized for the destination account. If it is, check that the connecting node and destination support host-bound SSH authentication.
When an attempt fails before signing, Subshell removes the subshell it created. You can retry with your selected file and passphrase in the browser; the desktop app asks you to choose the key again. If removal fails, follow the message to remove the failed subshell from the list before retrying.
Once a signature has been issued, a connection error can leave the login's outcome uncertain. Subshell keeps that subshell because it may contain a working connection. Check its terminal before starting another connection. A subshell opened with this one-use key needs a new SSH connection to authenticate again after it exits.
Start and verify the connection
Select Start SSH subshell. If you're using another node's keys and neither that node nor your account already trusts the destination, Subshell asks Connect to this destination? before signing in.
A host key is the destination machine's public SSH key. It identifies that machine; your login key or password identifies you. Remembering the host key lets SSH detect a different machine answering at the same address later. You don't need to generate, paste, or manage host keys in the dashboard.

Check the address. The dialog shows the destination's host fingerprint and warns that the fingerprint came from the destination itself, not an independent check. If you need to verify the machine, compare the fingerprint with one obtained from its administrator through a trusted channel. Choose Trust and connect to remember that identity and retry the connection, or Cancel to leave it untrusted.
First-connection trust
A key retrieved from the destination isn't independent proof that you've reached the right machine. Accepting it without checking the fingerprint trusts the first response. Subshell blocks later connections if the identity changes; it doesn't silently replace the saved identity. If that happens, stop and verify the change with the destination's administrator.
For these connections, Subshell stores the public host key and destination in the server's database, scoped to your account. The stored key isn't a login credential or a private key. Access checks protect the record through the API; the server operator controls the database, so this protection depends on trusting your Subshell server.
Connections using the connecting node's own keys or a password use that node's OpenSSH trust records instead. They automatically remember a previously unknown host key and reject a changed one. To verify a destination before that first connection, have the node's owner establish its trusted host key on the node first.
Once connected, the terminal shows the destination's shell. Its top bar has an SSH connection icon whose tooltip shows the connecting node, destination, and any port forwards declared for that subshell. If you selected password authentication, wait for its password prompt before typing. Only the owner signed in to the dashboard can type in an SSH subshell; MCP and other bearer credentials cannot send input. Session sharing lets other users view its output.
SSH presets and recent destinations
In the dashboard sidebar, open Settings → Presets → New preset → New SSH preset. This option is available from either the Agent or SSH tab. If your SSH library is empty, you can also select Create your first SSH preset on that tab.
Enter a Name, choose the connecting node and destination, then select an authentication option. Names can contain up to 120 characters. Select Save preset to keep these choices without starting a connection.
A preset's ⋯ menu offers Edit, Clone preset, Delete preset, and Connect. Connect opens the new-subshell form with those settings filled in; review them and select Start SSH subshell when you're ready. Editing or deleting a preset doesn't change an existing connection or reset a verified destination identity.
Presets save the resolved username, host, and port, along with the original SSH alias so its routing and key settings still apply. If that alias later resolves to a different address, Subshell blocks the connection until you edit the preset's destination to approve the new address. Recent destinations remain available as suggestions in the connection form, including separate entries for different usernames on the same host.
The authentication options determine what you save now and what you supply when creating a new SSH subshell:
- Use the connecting node’s keys uses that node's SSH configuration when connecting.
- Use another node’s keys reveals a node picker directly beneath the option. Choose the node and keys to save their source and public-key fingerprints. Subshell checks access and available keys again before connecting.
- Use a key from my machine saves the authentication preference. Choose and approve a key when creating a new SSH subshell; your key isn't saved in the preset.
- Enter a password when connecting saves the authentication preference. When creating a new SSH subshell, enter your password in the terminal when SSH asks for it.
Presets never store your private key, key file, passphrase, native approval, or destination password.
If you select Save as preset while launching and the connection fails, the saved preset remains available. Retrying the same choices doesn't create another copy. Previously remembered destinations aren't converted into named presets; create presets for the connections you want to reuse.
Port forwards
Forward ports through an SSH connection to reach a web app, database, or other TCP service. Each listening port lasts for the SSH connection and closes when the subshell ends.
Add a port forward
- In the dashboard, open Workspaces, find the Subshells section, then choose Add subshell from the ⋯ menu beside the grouping dropdown. If a workspace is open, select New subshell. Choose SSH terminal. Choose Connect from, enter the SSH destination, and choose how to authenticate.
- Under Port forwards, select Add port forward.
- Choose a kind from the table below. Enter Local port or Remote port and, for local or remote forwarding, Target host and Target port.
- Select Add port forward again to add the completed row to the connection. Repeat for more ports, up to 16 forwards. Use Remove to discard a row; to change one, remove it and add its replacement.
- Review the listed forwards, then select Start SSH subshell. Follow the authentication and destination-verification steps above.
| Kind | Where the port opens | Where the target is reached from |
|---|---|---|
| Local (-L) | The connecting node | The SSH destination. Use it for a web app or database reachable from that destination. |
| Remote (-R) | The SSH destination | The connecting node. Use it to make a service reachable from the destination. Its SSH server decides whether and how the listening port binds. |
| Dynamic SOCKS (-D) | The connecting node | The SSH destination. Configure a tool to use this SOCKS proxy; the tool chooses the target for each request. |
“Local” means the node selected under Connect from, which may be a different machine from your browser. Choosing a key from your laptop doesn't move the listening port to your laptop.

Reach a web app on the destination
Suppose a web app listens on 127.0.0.1:3000 on the SSH destination. Add a Local (-L) forward with Local port 8080, Target host 127.0.0.1, and Target port 3000. After connecting, open http://127.0.0.1:8080 in a browser running on the connecting node. Here, the target's 127.0.0.1 means the SSH destination.
For the reverse direction, choose Remote (-R) with Remote port 8080 and the same target values. Programs on the SSH destination can then use its port 8080 to reach port 3000 on the connecting node. The target's 127.0.0.1 now means the connecting node.
For Dynamic SOCKS (-D), enter only a Local port, such as 1080, then configure a SOCKS-capable tool on the connecting node to use 127.0.0.1:1080.
Bind addresses and access
Local and dynamic forwards bind 127.0.0.1 on the connecting node by default. Programs on that node, including those run by other OS users, can reach the port. Opening the dashboard elsewhere doesn't make that port available there.
Allowing access from other machines
A non-loopback bind can let other machines route traffic through your SSH connection to services it can reach. Only enable it when you intend to give those machines that access.
The node's owner can open Nodes, select the connecting node, and turn on Allow wide port forwards in its SSH card while Allow SSH is enabled. An administrator manages this for the built-in node on the server host. See Manage a node.
With wide forwards allowed, the form shows Bind address. Leaving it blank keeps the default; a value such as 0.0.0.0 requests all IPv4 interfaces. A non-loopback address requires this permission even for a remote forward, and the destination's SSH server still decides how a remote port binds. Turning the setting off blocks future wide-bind launches; existing forwards keep running until their connection ends.
Reuse and troubleshoot forwards
SSH presets save the listed forwards with the other connection choices. You can add them in Presets → New preset → New SSH preset, or select Save as preset in the connection form. Applying a preset fills the rows for review before you connect. Editing the preset doesn't change an existing subshell.
If a requested port is already taken, the destination's shell can still open while SSH prints a warning that the forward couldn't bind. Check the terminal and try the service through the listening port; a working shell alone doesn't prove the forward is available. Choose an unused port and start a new SSH subshell if needed.
Forwards declared in the connecting node's SSH configuration through LocalForward, RemoteForward, or DynamicForward remain unsupported and cause connection resolution to be refused. Remove those settings from the configuration used by the connection and add the forwards explicitly in Subshell's form or preset instead. Agent forwarding, X11 forwarding, and tunnel devices remain unsupported.
The SSH connection tooltip shows the declared forwards, not a live check of their availability. Users who can view the subshell can see this summary, and each launch records a forwarding summary in the audit trail. If a node is too old to support forwards, update the machine named in the error before trying again.
Make the destination a node
As the SSH subshell's owner, open its ⋯ menu and choose Set up Subshell here… when available. Review the confirmation before running the installer: it installs Subshell on the destination and enrolls it as a node you own. Your SSH subshell keeps running.
Update the server and connecting node together before using this action. The installer keeps its setup key out of process arguments. If it reports that the downloaded node cannot accept a setup key privately, update the server’s node download, check the destination, and run Set up Subshell here… again.
A subshell opened with a one-time key cannot reuse that key for this installer. Run the node setup command in its existing terminal, or reconnect using a node's keys first.
This requires node enrollment to be allowed and an SSH login that works without interactive prompts. Password-only login can't supply a stored password to the installer. You can close and reopen the dialog to check progress. Results remain available for one hour while the server keeps running. Progress isn't retained across a server restart; check Nodes and the destination before retrying an interrupted installation. If it reports enrollment without a confirmed connection, open the new node's page and check its service before trying another installation.
Next steps
Use Manage a node to change Allow SSH. Turning it off blocks new outgoing connections and stops the node from supplying keys. It doesn't change incoming SSH access to that machine.
Edit on GitHubLast updated on
