STACIO WIKI · User Guide

Stacio Remote Connections Guide

1. Connection paths at a glance

Stacio provides three main connection paths:

Regardless of the path, remote-account permission, host-network policy, and protocol security boundaries are defined by the target environment.

Most sessions connect directly to an IPv4 address such as 192.168.1.20. When SSH uses a non-default port, write 192.168.1.20:2222. Environments with stable DNS can use server.example.com or server.example.com:2222. Examples below use IP first and show equivalent hostname forms where useful.

2. Quick Connect

2.1 IP, port, and hostname conventions

Quick Connect has one SSH Target field that accepts these common forms:

In this guide, IP:port means a complete network endpoint. It does not mean every UI writes both values in the same field:

• Quick Connect's one-line target accepts [username@]IP[:port] and [username@]hostname[:port];
• New Session, Edit Session, and manual ProxyJump use separate Host and Port fields;
• a separate Host field contains only 192.168.1.20 or server.example.com, never ssh://, root@, or :2222;
• a separate Port field contains only a number such as 22 or 2222.

2.2 Supported Quick Connect input

Quick Connect is currently for SSH and supports:

192.168.1.20
192.168.1.20:2222
root@192.168.1.20
deploy@192.168.1.20:2222
host.example.com
user@host.example.com
user@host.example.com:2222
ssh://deploy@192.168.1.20:2222

The rules are:

• port 22 is used when no port is present;
• the current macOS username is used when no username is present;
• IP addresses and hostnames use the same username and port rules;
• input is rejected if username, host, or port is empty after parsing;
• never put a password or private-key passphrase in the target string. Enter it in the authentication control or reference a saved credential;
• when Save as session after a successful connection is selected, Stacio creates a session only after the connection succeeds.

If you do not save the session, a local credential reference created for a temporary secret is cleaned up when the connection completes or fails. If you save the session, the reference is retained with the session.

2.3 Recommended uses

• Validate an IP or hostname, port, and account.
• Confirm a host key for the first time.
• Enter a host temporarily for a one-off task.
• Add tags, environment, AI policy, and jump-host configuration only after a successful connection.

3. Create a saved session

Choose File > New Session, then choose a protocol. The current New Session view can save:

• SSH;
• Telnet;
• VNC;
• SFTP;
• FTP;
• SCP;
• Serial;
• Local Terminal.

RSH, XDMCP, Mosh, S3, and WSL show as unsupported or not saveable in the current version. Do not treat planned items as available connections.

3.1 Common fields

Fill common saved sessions like this:

Do not enter 192.168.1.20:2222 in Host; it mixes a port into the saved-session host string. Even when a protocol has a default port, retain the explicit value that the UI fills for future review and audit.

Direct IP works well for stable addresses, LANs, VPNs, and fixed public endpoints. Hostnames work well where DNS manages address changes or standardized names. When a hostname connection fails, record the configured hostname, resolved IP, and port, but do not silently replace a saved hostname with one resolution result.

3.2 Naming and tags

Give a session a self-explanatory name, for example:

prod-api-01
staging-postgres-bastion
lab-switch-console

Tags can add information such as project-a, linux, database, or favorite. A production session must set Environment to Production; a prod substring in the name is not a substitute for the production policy.

4. SSH authentication

4.1 Password

1. Choose Password for authentication.
2. Enter and save the password.
3. Stacio stores a credential reference in the session database and the secret in its local encrypted credential store.
4. If the credential file is missing or cannot be decrypted, Stacio asks you to enter and save it again during connection.

Never put a password in a session name, tag, startup command, environment variable, connection script, or import file.

4.2 Private key

1. Choose Private Key for authentication.
2. Select a local private-key path such as ~/.ssh/id_ed25519.
3. Save the passphrase to the local credential store when the key has one.
4. Confirm that the current macOS user can still read the private-key file.

Stacio stores the key path and does not put private-key contents into ordinary session export. If you move or delete the key, edit the session and select it again.

4.3 SSH agent

With SSH Agent, Stacio does not require a saved password or private-key passphrase. Success depends on an available SSH agent, the correct key being loaded, and the remote host accepting the matching public key.

5. Host-key confirmation

5.1 First connection

Stacio probes the host key before it sends authentication credentials. On a first connection it displays:

• host and port;
• key algorithm;
• SHA-256 fingerprint;
• why the host is unknown.

Host-key trust uses the configured host string plus port as the connection identity. These are distinct confirmations and saved records, even if they might reach the same machine:

192.168.1.20:22
192.168.1.20:2222
server.example.com:22

Changing IP to hostname, hostname to IP, or changing the port can therefore trigger a new first-trust prompt. Verify the fingerprint through a trusted channel each time.

Trust sources include a cloud console, the host administrator, an asset system, or another trusted channel. After you confirm it, Stacio persists the trust decision locally.

5.2 Fingerprint changes

When a fingerprint differs from the saved value, Stacio blocks the connection by default. Legitimate causes include a host rebuild, SSH host-key rotation, IP/DNS reassignment, or a changed jump target. It can also indicate a man-in-the-middle attack.

Handle it in this order:

1. Stop the connection. Do not retry repeatedly or accept the new fingerprint immediately.
2. Verify the real target, DNS, port, VPN, and jump host.
3. Obtain the new fingerprint through an independent trusted channel.
4. Update the local trust record only after confirming the change is authorized.
5. Keep the time, old/new fingerprint summaries, and confirmer in diagnostics or a change record.

5.3 Jump hosts

ProxyJump verifies jump-host and target-host fingerprints separately. A connection is blocked when either side is not trusted.

6. Jump hosts and ProxyJump

The Jump Host area for an SSH session provides:

• Do not use;
• Existing Session: reference a saved SSH, SFTP, or SCP session ID;
• Manual: enter jump host, port, user, credential ID, and private-key path.

Prefer an existing session so that host, account, credentials, and fingerprints are maintained in one place. Manual mode is useful for a temporary or not-yet-saved bastion entry point.

Manual mode also uses separate fields. For a jump endpoint 10.0.0.5:2222, enter Host = 10.0.0.5 and Port = 2222. For a hostname, enter Host = bastion.example.com and Port = 22. Do not paste a complete endpoint into the jump Host field.

The connection path is:

Stacio -> Jump host SSH -> Target host SSH

Notes:

• ProxyJump is controlled by a License;
• a jump session must be SSH, SFTP, or SCP;
• target and jump hosts each use their own authentication and host-key validation;
• a reachable jump host does not prove that the target host is reachable, so diagnose the two segments separately;
• do not nest ssh manually in a connection script to bypass Stacio's jump-host configuration and audit boundary.

7. Post-connection actions and timeouts

A saved SSH session can configure:

Only a Connection Script is appropriate for commands that must run automatically. Keep it idempotent, auditable, and low risk. Do not configure automatic change scripts for production environments.

8. Other protocols

8.1 SFTP and SCP

• An SFTP session opens the built-in SFTP file workspace directly.
• An SCP session uses SSH authentication and file-transfer context.
• Both default to port 22 and use the SSH host-key workflow.
• A common endpoint is 192.168.1.20:22; a custom port can be shown as 192.168.1.20:2222, but saved sessions keep host and port in separate fields.
• See the Files guide for file operations, transfer queues, and editing behavior.

8.2 FTP

• FTP defaults to port 21.
• A common IP endpoint is 192.168.1.30:21; a hostname form can be files.example.com:21.
• Stacio displays a plaintext-protocol risk warning before opening it.
• Use it only on trusted or additionally encrypted networks.
• Resume support, directory listing, and particular file operations depend on the server.

8.3 Telnet

• Telnet defaults to port 23.
• A common network-device endpoint is 192.168.1.40:23; a non-default port still belongs in the separate Port field.
• The protocol does not encrypt usernames, passwords, or terminal content.
• The application displays a plaintext-protocol warning.
• Use it only for legacy devices on isolated networks that cannot be upgraded.

8.4 VNC

• VNC defaults to port 5900.
• Common endpoints include 192.168.1.50:5900 and desktop.example.com:5900.
• The installed package must include a usable graphical adapter.
• When an adapter is missing or the protocol is unsupported, the workspace shows diagnostics instead of establishing a graphical connection.
• VNC authentication and transport security also depend on the server; protect it through an SSH tunnel when needed.

8.5 Serial

A serial session needs a device path plus baud rate, data bits, stop bits, parity, flow control, and backspace key configuration. Built-in presets cover common network-device 9600 8N1 and high-speed console 115200 8N1 settings.

When a device cannot be opened, check:

• whether it still appears in macOS;
• whether another program holds it;
• USB/Bluetooth drivers and permissions;
• actual console parameters on the switch or device;
• cables, adapters, and hardware flow-control requirements.

8.6 Local Terminal

Local Terminal runs on the Mac and does not pass through a remote SSH session. When using a local Agent, distinguish a local shell from a remote terminal operated through stacio-remote.

9. Import sessions

9.1 Supported sources

File > Import Sessions currently lists:

Bastion-host import is a License-controlled connection-orchestration capability.

9.2 Secure import process

1. Select the explicit source type and original export file.
2. Review names, groups, protocol, target, and conflicts in the preview.
3. Confirm that port and username have not been parsed incorrectly.
4. Choose Skip, Replace, or Rename for duplicate session names.
5. Reconfigure passwords, tokens, and private-key passphrases after import.
6. Verify host keys again on first connection.

Import does not treat plaintext passwords from external files as trusted credentials. Even Stacio-format import filters credential references and automatic-execution fields; for example, connection scripts or startup commands in an imported file are not silently inherited.

9.3 Import failure

Open View > Diagnostics and inspect the Import Report. Check in particular:

• whether the file format matches the selected source;
• whether the vendor version is supported;
• whether a compressed package is complete;
• invalid port, host, or protocol fields;
• the duplicate-session conflict policy;
• whether the current License allows the requested import module.

10. Session maintenance

10.1 Change user temporarily

Choose Connect As... from a session context menu to enter a username and open a temporary connection without changing the saved session. This is useful when verifying the same host with a different least-privilege account.

10.2 Ping host

Ping Host continuously shows system Ping output and lets you stop it. Ping accepts only an IP or hostname, not IP:port; an unsuccessful Ping does not prove SSH is unavailable because ICMP may be disabled, routing may differ, or local permission may be restricted. To test an endpoint such as 192.168.1.20:2222, use Diagnostics > Port Check and enter host 192.168.1.20 and port 2222 separately.

10.3 Copy, move, and export

• Copying a session creates an independent configuration; review the name, environment, and credential reference after copying.
• Moving changes only the sidebar group.
• Export is suitable for non-sensitive configuration migration and is not a credential backup.
• A desktop shortcut still delegates the actual connection and host-key validation to Stacio.

11. Disconnects and reconnecting

An SSH terminal distinguishes connecting, running, disconnected, reconnecting, and closed states. Following a network interruption it can reconnect with increasing delay; manually closing or cancelling stops automatic reconnection.

Before reconnecting, check:

1. The active tab still points to the intended session.
2. VPN, Wi-Fi, Ethernet, or proxy access has recovered.
3. Host and port have not changed.
4. Credentials are still valid and the SSH agent still has the right key.
5. The host key has not changed without verification.

Automatic reconnection restores a connection only. It does not guarantee that a foreground remote program, transaction, file write, or unfinished command continues from where it stopped.

12. Troubleshooting errors

When reporting an issue, include the Stacio version, macOS version, protocol, target port, time of failure, whether a jump host was used, authentication type, and redacted diagnostics. Do not submit secrets or private-key contents.