STACIO WIKI · Operations Guide

Stacio Remote Operations Guide

1. Operating principles

Stacio provides terminals, the device dashboard, files, tunnels, diagnostics, and Agent capabilities. It does not replace organizational authorization, monitoring platforms, backup systems, or change approval. Follow this order for remote work:

Confirm target -> Read-only baseline -> Assess impact -> Prepare backup and rollback
-> Minimum change -> Targeted validation -> Record outcome -> Restore if needed

Before you start, confirm:

• the selected terminal, session name, IP or hostname, port, and environment;
• whether the task involves one host or several;
• the current account's privilege and whether elevation is actually necessary;
• whether the work is read-only diagnosis or changes remote state;
• whether production already has a change window, backup, and rollback owner.

1.1 Confirm a target with IP, hostname, and port

Do not identify a target from its session name alone. Compare the endpoint configured in Stacio with identity information returned by the remote shell:

Saved sessions hold Host and Port in separate UI fields; the table only combines them into an endpoint for review. Identical hostname output does not prove the entry endpoint is identical, and identical IPs do not make port differences irrelevant. For a hostname, an incident record should retain configured hostname, resolved IP at the time, and port. For an IP, verify it has not been reassigned through DHCP, cloud resource reuse, or changed NAT rules.

2. Build a reliable operations workspace

2.1 Mark sessions

In New/Edit Session > Automation, set:

• Environment: development, staging, or production;
• AI Execution: follow global, block execution, command cards only, read-only automatic, or confirm each command;
• tags for system, business, region, role, and responsible team.

Production sessions must be explicitly marked Production. The mark participates in MultiExec and AI/Agent confirmation policy; writing prod in a name is not equivalent to a production environment policy.

2.2 Splits and context

Splits are useful to view at the same time:

• application logs and service status;
• host resources and a business-health endpoint;
• pre-deployment version and post-deployment verification;
• primary and replica state.

Click the intended pane before opening Files, Dashboard, or AI so the right-side capability binds to the right terminal. Splits do not synchronize input; synchronized input requires explicitly entering MultiExec.

2.3 Terminal readability

Consider these settings in Settings > Terminal for operational work:

• enable timestamps to correlate an incident timeline;
• increase scrollback for long-log tasks;
• enable long-command completion notifications;
• enable multiline-paste confirmation;
• use Pause Output for high-output work, and check for an omitted-bytes notice after resuming;
• use Command+F to find errors, request IDs, process names, or times.

3. Device Dashboard

3.1 Open it

1. Select a connected SSH tab.
2. Choose View > Show/Hide Device Dashboard or the Device Dashboard toolbar control.
3. Wait for at least two sample intervals; CPU and rate metrics normally need two samples to calculate.

The dashboard is a License-controlled advanced capability.

3.2 Metric coverage

3.3 Compatibility and refresh settings

In Settings > Dashboard, configure:

• refresh interval from 1 to 30 seconds;
• whether to retain the last successful data after collection failure;
• whether network and disk modules are visible;
• disk count and chart sample points;
• whether virtual or container network interfaces are automatically hidden;
• CPU, memory, and disk alert thresholds and consecutive-breach count.

For cross-region, low-performance, or BusyBox hosts, increase the refresh interval to avoid probes hurting interaction. Alerts appear only after configured conditions occur continuously. macOS notifications are hints, not a replacement for centralized monitoring.

3.4 Linux probe boundaries

The dashboard currently prefers /proc/stat, /proc/meminfo, /proc/net/dev, /proc/mounts, and compatible df output, targeting Linux environments such as CentOS/RHEL, Rocky, Alma, Fedora, Ubuntu, Debian, Alpine/BusyBox, and openSUSE.

Only partial metrics may appear when:

• the target is not Linux;
• /proc or mount information is restricted inside a container;
• the remote account lacks read or execution permission;
• a minimal system lacks compatible df;
• the SSH connection is interrupted or the shell is occupied by a foreground program.

4. Host resource inspection runbook

The following examples are read-only and target common Linux systems. Confirm the commands exist and avoid running expensive sampling across many hosts at once.

4.1 Identity and system

date -Is
hostname
whoami
uname -a
uptime

Record time, hostname, user, kernel, and load first, so evidence can be tied to the actual host.

4.2 CPU and processes

uptime
top -b -n 1 | head -40
ps -eo pid,ppid,user,stat,%cpu,%mem,etime,comm,args --sort=-%cpu | head -25

Distinguish:

• load average from CPU-core count;
• an instantaneous top view from sustained sampling;
• user, system, I/O wait, and steal time;
• one high-CPU process from whole-host pressure;
• brief usage caused by the sampling command itself.

4.3 Memory and swap

free -h
ps -eo pid,user,rss,vsz,%mem,etime,comm,args --sort=-rss | head -25

Prioritize available memory rather than free memory alone. Used swap is not necessarily current pressure; combine it with page activity, OOM logs, and application latency.

4.4 Disk and inodes

df -hT
df -ih

To locate a large directory, first constrain the command to a known filesystem and directory rather than scanning / without bounds:

du -xhd1 /var 2>/dev/null | sort -h

Do not run an unrestricted whole-disk du until mount points, workload peak, and directory size are understood.

4.5 Ports and network

ip -brief address 2>/dev/null || ifconfig
ip route 2>/dev/null || netstat -rn
ss -lntup 2>/dev/null || netstat -lnt

Diagnostics > Port Check can quickly test host and port. To test 192.168.1.20:2222, enter host 192.168.1.20 and port 2222 separately; for a hostname, enter server.example.com and its port. A reachable port proves TCP reachability only, not protocol authentication or application health.

5. Service-unavailable runbook

5.1 Gather read-only evidence first

systemctl status <service> --no-pager
journalctl -u <service> --since '30 minutes ago' --no-pager | tail -200
ss -lntp
curl -fsS -D- --max-time 10 http://127.0.0.1:<port>/<health-path>

Before replacing placeholders, confirm the service manager, port, and health path. Use the corresponding service tools for non-systemd systems.

5.2 Build the failure chain

Validate each layer in order:

IP or hostname resolution -> routing/NAT/load balancer -> listening port -> process/container
-> application health -> database/cache -> upstream and downstream dependencies

Do not claim the business is restored merely because a process is running, and do not restart a service just because an external request failed.

5.3 Gate before a change

Before changing configuration, restarting, rolling back, or deploying, confirm:

• there is evidence connecting the suspected fault to the intended change;
• current configuration, version, and runtime state are saved;
• a new, verifiable backup exists for this change;
• rollback commands and an owner are clear;
• blast radius, connection interruptions, and data risks are known;
• production changes have required approvals.

6. File and transfer failure runbook

6.1 A directory will not open

1. Confirm Files is bound to the right SSH, SFTP, or FTP session.
2. Run pwd and a read-only directory check in the terminal to confirm account permission.
3. Check whether the path was deleted, renamed, or contains unusual characters.
4. Refresh the directory; if it still fails, open View > Diagnostics.

6.2 Transfer failure

Use the transfer queue to inspect job ID, direction, source, target, progress, diagnostics, and logs. Pause/resume or resume-transfer availability depends on protocol and server support.

7. Tunnel failure runbook

1. Confirm the License and SSH/SFTP/SCP endpoint are available.
2. For Local or Dynamic tunnels, check that the local port is free.
3. Verify separately: Mac to SSH endpoint, SSH endpoint to target, and client to local listener.
4. For Remote tunnels, also check server support for remote forwarding and external binding.
5. Review the tunnel row's state, detail, access count, active connections, and inbound/outbound bytes.
6. When automatic reconnect keeps failing, stop it manually, correct network or credentials, then start again.

See Tunnels for complete fields and examples.

8. Diagnostics panel

Choose View > Diagnostics to view or run:

• current runtime diagnostics and severity;
• host and port reachability checks;
• session import reports;
• MultiExec and AI/Agent audit records;
• application-log search, level filtering, refresh, export, and cleanup;
• diagnostic-bundle export.

Diagnostic bundles redact data and are limited by audit-count, log-line, and Include Application Logs settings in Settings > Security. Preview before exporting, especially hostnames, business paths, request content, and log snippets.

9. Operations with AI and local Agent

Stacio provides two working modes:

Before using either mode:

1. Check the current target terminal and remote directory.
2. Prefer read-only checks and explicit evidence.
3. Use Confirm Each Command, or at least Read-only Automatic, in production.
4. For changes, require backup location, validation outcome, and rollback method in the result.
5. Report each failed target separately; never present partial success as complete success.

See Agent Capabilities and Security for the full Agent boundary.

10. Changes, validation, and rollback

10.1 General change checklist

1. Record pre-change version, configuration summary, service state, and health outcome.
2. Create a timestamped backup that does not overwrite history.
3. Verify the backup exists, is readable, and has a reasonable size; use native backup tools for databases where available.
4. Change only the minimum scope directly related to the fault or request.
5. Run a configuration-syntax or dry-run check first.
6. After applying a change, validate process, port, logs, health endpoint, and business request.
7. Compare important values before and after the change.
8. Stop expanding a failed change and restore according to the plan.
9. Run read-only validation again after rollback.

10.2 Completion standard

Do not announce a fix when any of these is missing:

• evidence of current state;
• targeted validation aligned with the goal;
• per-target results for multi-target work;
• backup and rollback information for changes;
• residual-risk and unverified-item disclosure.

11. Incident response checklist

11.1 When you discover an anomaly

1. Confirm target, time, and affected scope.
2. Pause automation, MultiExec, or further changes.
3. Preserve current terminal, log, metric, and audit evidence.
4. Decide whether an account, host, tunnel, or credential needs isolation.
5. Notify the relevant service, network, security, or database owner.
6. Contain and recover after approval.
7. Validate business recovery and continue observation.

11.2 Escalation material

At minimum, give the next responder:

• Stacio and macOS versions;
• session name, protocol, and environment, plus redacted IP/hostname and port; record the resolved IP for hostname use;
• start time, timezone, and current impact;
• read-only checks already performed and important output;
• changes made, backup location, validation, and rollback outcome;
• time range of diagnostic bundle or logs;
• remaining unverified hypotheses and the recommended next step.

Do not attach passwords, tokens, private keys, private-key passphrases, full environment variables, or unnecessary customer data.

12. Operations alert reference