STACIO WIKI · User Guide

Stacio Getting Started Guide

1. What Stacio does

Stacio brings common remote work into one native macOS workbench:

• save, group, and search SSH, SFTP, FTP, SCP, Telnet, VNC, serial, and local-terminal sessions;
• use local and remote terminals in tabs or split panes;
• browse, search, upload, download, edit, and back up remote files;
• manage Local, Remote, and Dynamic SSH tunnels;
• view CPU, memory, network, and disk metrics for Linux hosts;
• organize repetitive work with MultiExec, macros, the AI assistant, and a local Agent;
• retain necessary local session, transfer, diagnostic, and audit information.

Some advanced entry points are controlled by a License. Without a valid entitlement, their buttons or menu items remain disabled and show an upgrade hint.

2. System requirements and installation

2.1 System requirements

• macOS 14 or later;
• network access to the target host;
• a known target IP address or hostname, plus any non-default service port;
• an account and credentials for the target protocol;
• for serial use, a device path that macOS can recognize;
• for VNC or other graphical capabilities, an installed package that includes the required adapter.

2.2 Installation guidance

1. Download the installer for your Mac architecture from the official Stacio release page.
2. Open the DMG and move Stacio to Applications as instructed by the installer window.
3. Start Stacio from Applications and check that the version in About Stacio matches the downloaded version.
4. If macOS warns about the source or signing, do not bypass platform security blindly. First verify the package source, integrity, and architecture.

Official releases: https://github.com/Fengoffer/Stacio/releases

3. Know the workbench

3.1 Session list on the left

The left side manages saved sessions and groups:

• the search field filters by session name, host, or tag;
• Recently Used shows up to five recently opened sessions and can be disabled in Settings;
• sessions tagged favorite, favorites, or the Chinese favorite label appear in Favorites;
• sessions and groups support drag-and-drop ordering and movement;
• a session context menu can provide Connect As, Ping, Edit, Copy, Move, Export, Rename, and Delete.

Deleting a session removes its saved configuration and local edit cache, but does not automatically delete a credential from the local credential store.

3.2 Central workspace

The central area hosts terminals, files, browser, and graphical sessions:

• each connection normally opens in a tab;
• tabs can be renamed, colored, duplicated, pinned, detached, fullscreened, or closed in batches;
• terminals can use a single pane, vertical split, horizontal split, or grid split;
• the active tab determines the context used by Files, the dashboard, AI, and command history on the right.

3.3 Toolbar and Panels menu

Common entry points include:

• New Session: create and save a connection;
• Import Sessions: import configuration from another terminal tool;
• MultiExec: choose several terminals and synchronize input;
• Split: choose a terminal layout;
• Files, Browser, Tunnels, Device Dashboard, and AI: open the respective capability;
• Panels: open Files, Browser, Tunnels, Diagnostics, Macros, Command History, Dashboard, or AI in one place;
• Inspector: show or hide the right-side panel.

3.4 Right-side inspector

The inspector can show:

• files and the transfer queue;
• SSH tunnels;
• the built-in browser;
• diagnostics, import reports, audit records, and application logs;
• the device dashboard;
• macros and command history;
• the AI assistant.

4. Make your first SSH connection

4.1 Use Quick Connect

1. Click Quick Connect in the toolbar, or enter a connection target on the start page.

2. Enter any of these forms:

   192.168.1.20
   192.168.1.20:2222
   root@192.168.1.20
   deploy@192.168.1.20:2222
   server.example.com
   deploy@server.example.com
   deploy@server.example.com:2222
   ssh://deploy@192.168.1.20:2222

3. Confirm the username, authentication method, and credentials.

4. To retain it, select Save as session after a successful connection and enter a session name.

5. Click Connect.

6. On a first connection, verify the host, port, algorithm, and SHA-256 fingerprint before deciding whether to trust it.

In most cases you can connect directly to a server IPv4 address. If you enter only an IP or hostname, Stacio uses SSH port 22 and the current macOS username. Append :2222 for a custom port, and prefix deploy@ to specify a user.

Quick Connect keeps the target in one field, while a saved session uses separate fields. For example, save deploy@192.168.1.20:2222 as:

Do not paste the complete deploy@192.168.1.20:2222 value into a saved session's Host field.

4.2 Create a saved session

1. Choose File > New Session or press Command+Shift+N.

2. Select SSH (Secure Shell).

3. Fill in name, host, port, and user. Host contains only 192.168.1.20 or server.example.com; enter the port separately.

4. Choose an authentication method:

   • Password: enter a password and save it to the Stacio local credential store;
   • Private Key: choose a private-key path and save its passphrase if it has one;
   • SSH Agent: authenticate through an available SSH agent.

5. Add tags, environment, AI execution policy, connection timeout, and a jump host as needed.

6. Click Save, then double-click the session in the left sidebar to open it.

After a connection succeeds, the terminal header shows a connection summary. When a session has a Startup Command or Environment Variables, the current version displays them as a Startup plan but does not execute them automatically. Only a Connection Script is written and executed after an SSH terminal is ready. See Automation.

5. Everyday terminal work

5.1 Create and close terminals

• File > New Local Terminal or Command+N: open a local shell;
• File > Close Current Terminal or Command+W: close the active tab;
• when the Settings option to confirm before closing is enabled, Stacio asks again before closing;
• if SSH tunnels are running when the app exits, Stacio warns that exiting stops them.

5.2 Find, copy, and paste

• Terminal > Find or Command+F: search the current terminal output;
• Command+C and Command+V: copy and paste;
• enable Copy on Selection in Settings if desired;
• enable confirmation before multiline paste to avoid sending an entire script directly to a remote shell.

5.3 Split panes

1. Open one or more terminal tabs.
2. Choose Split in the toolbar or Terminal > Split Layout.
3. Choose a single, vertical, horizontal, or grid layout.
4. Click the target pane so Files, Dashboard, AI, and command history bind to the correct terminal.

A split is only a layout. It does not send input to every pane. Use MultiExec for synchronized input and inspect the target list before sending.

5.4 Output and display settings

In Stacio > Settings > Terminal, you can configure:

• font, theme, cursor, command highlighting, and hardware acceleration;
• scrollback line count, line numbers, timestamps, and millisecond display;
• SSH keepalive interval;
• right-click behavior, Option/Meta, and macOS input-method compatibility;
• command suggestions, history candidates, and accepting a suggestion with Tab;
• notifications when long commands finish;
• multiline-paste protection and pasting an image as a path.

6. Open Files, Dashboard, Tunnels, and AI

6.1 Files

1. Select a connected SSH terminal, or open an SFTP, FTP, or SCP session.
2. Choose View > Files or the Files toolbar control.
3. Use the breadcrumb, Up, Refresh, Search, and hidden-file controls to browse directories.
4. Upload, download, and edit activity appears in the transfer queue.

See the full Files guide.

6.2 Device Dashboard

1. Select a connected SSH tab.
2. Choose View > Show/Hide Device Dashboard.
3. Review system information, CPU, memory, network, and disks.
4. In Settings > Dashboard, adjust refresh interval, modules, history length, and alert thresholds.

The dashboard depends on remote Linux probes. Some metrics can be unavailable if the target lacks /proc or compatible df output.

6.3 Tunnels

Choose View > Tunnels, then create a tunnel bound to an SSH, SFTP, or SCP session endpoint. Prefer listening on 127.0.0.1 by default. See Tunnels for the full guide.

6.4 AI assistant

1. In Settings > AI and Execution, configure a model provider, Base URL, model, and API key.
2. Select the current terminal and open View > AI Assistant.
3. Choose rule suggestions or model reasoning and describe the troubleshooting question.
4. Review each command card's target, risk, and content before execution.

The AI API key is stored in the Stacio local credential store. Whether recent terminal output is attached depends on the Terminal Context setting.

7. Session management

7.1 Groups and search

• Create groups and subgroups in the sidebar;
• drag sessions or groups to change their placement;
• use a group context menu to rename, delete, or export it;
• when deleting a non-empty group, either delete its sessions too or remove only the group and move sessions to the root.

7.2 Import and export

File > Import Sessions supports Stacio, Xshell, MobaXterm, WindTerm, SecureCRT, FinalShell, Termius, Electerm, generic JSON, and bastion-host sources. A preview and conflict state appear before import.

Normal export is not a credential backup. When migrating one session that contains credentials, use the application's encrypted session-migration flow and protect the migration passphrase separately.

7.3 Context-menu shortcuts

A session context menu can include:

• Connect As...: temporarily change the username without changing the saved session;
• Ping Host: continuously show the system Ping output until you stop it;
• Copy Session, Move Session, and Rename Session;
• Export Session, create a desktop shortcut, save as default preset, and copy session settings;
• Edit Session and Delete Session.

Batch or group export can be controlled by a License.

8. Settings and local data

Stacio > Settings primarily contains:

The session database, application logs, credential store, and edit cache are stored in the current macOS user's Application Support directory. Use Settings > Security > Local Storage to copy the actual path.

9. License and offline use

• Use Help > License to view entitlement state, edition, expiration, and grace information;
• online activation is supported, as are exporting a device request and importing a signed offline authorization file;
• a valid entitlement that has been verified and persisted can continue working offline, subject to its state and expiration;
• a License controls Stacio feature entry points only. It does not grant remote-server permissions;
• when an entitlement is unavailable, restricted entry points remain disabled. Do not attempt to bypass them by changing local databases or configuration.

10. Common questions

If the issue remains unresolved, open View > Diagnostics, collect redacted errors, application logs, and timestamps, then submit the escalation material described in Remote Operations.