STACIO WIKI · Automation Guide

Stacio Automation Guide

1. Automation capability boundary

Stacio currently provides controlled automation around already-open terminals. It is not a general task-scheduling platform.

The current version has no standalone cron-style job list, time trigger, calendar trigger, daemon-task orchestration, or timed failure-compensation queue. For scheduled work, use remote cron/systemd timer or macOS launchd after explicit approval; the respective system owns permission, logging, alerting, and disabling. Stacio does not manage those external schedules automatically.

2. Security baseline before automation

Before any automation, answer:

1. Which host, account, environment, and runtime are targeted?
2. Is input read-only, ordinary write, network activity, or destructive work?
3. Are multiple targets fully homogeneous, or do versions, directories, and permissions differ?
4. Is there a verified pre-change backup?
5. Which command or business request validates completion?
6. How will you stop, roll back, and confirm recovery after failure?

Verify an automation target by complete endpoint rather than session alias only:

The table is a review format. Saved sessions still hold Host and Port separately. Session names can be stale or duplicated and runtime IDs can change after reconnect, so reconfirm the active endpoint before every batch or Agent action.

In production, neither command sent, task queued, nor Agent finished is proof of successful change. Completion needs real terminal output and targeted validation evidence.

3. Session environment and AI policy

In the Automation area of New Session or Edit Session, set:

3.1 Environment

Environment is security metadata and does not change the remote host itself. Recheck it after copying, importing, or renaming a session; do not infer environment from a name alone.

3.2 AI execution policy

Deny patterns take precedence; production enforces conservative approval; a session may be stricter than the global policy. Allow patterns and risk classification cannot prove command semantics are absolutely safe, especially for pipelines, redirection, command substitution, and wrapper scripts.

4. Actions after connecting

4.1 Actual differences between three fields

Startup plan explicitly shows (not executed automatically). It is useful to record an intended startup approach or give a user text to inspect and copy, but cannot be relied on for cd, export, service start, or deployment.

Only Connection Script executes automatically, and only on SSH terminals. Serial, Telnet, and Local Shell do not use that SSH-injection path.

4.2 Configure a connection script

1. Edit an SSH session.
2. Enter one or more shell lines in Actions After Connecting > Connection Script.
3. Save the session and reconnect.
4. Observe the post-connect directory, prompt, and command output.
5. Check failure information in View > Diagnostics.

Read-only example:

cd /srv/app
pwd
git status --short --branch

Stacio appends a newline and writes the script silently, attempting to filter script echo. Script output still enters the current terminal. Both initial connect and later reconnect enter the ready flow, so a script must be safe to repeat.

4.3 Connection-script design principles

• Keep it short, readable, and idempotent.
• Prefer changing directory, setting a prompt, and read-only inspection.
• Do not automatically deploy, restart, delete, migrate a database, or change a firewall.
• Do not include passwords, tokens, private-key passphrases, or long-lived secrets.
• Do not assume shell type, current directory, or sudo permission.
• Make failure visible at every step.
• Design for repeated execution after disconnect and reconnect.

Connection scripts are stored in session configuration, not the credential store. Treat them as sensitive configuration when copying session settings, reading a local database, or sharing diagnostics.

4.4 Import and connection scripts

When importing sessions from an external tool or ordinary Stacio configuration, automatic-execution fields are not silently inherited. Review and configure a connection script manually after import so an external file cannot execute commands through the import path.

5. MultiExec

MultiExec is License-controlled and synchronizes keyboard input to multiple opened terminals.

5.1 Start interactive MultiExec

1. Connect and verify at least two terminals individually, including each IP/hostname, port, account, and environment.
2. Click MultiExec in the toolbar.
3. In the target list, select only the terminals that need synchronization by complete endpoint, not similar session names.
4. When the workspace is already a multi-terminal split, Stacio can use its current split targets.
5. Confirm to place targets into a MultiExec grid workspace.
6. Type in any unpaused pane to synchronize content to other unpaused targets.

Executable terminals can include Local Shell, SSH, Serial, or Telnet. A disconnected remote terminal will not receive input successfully.

5.2 Pause one target

Each remote pane can choose Pause Sync for This Terminal. After pausing:

• that pane still receives direct user input;
• input from other panes is not broadcast to it;
• input made in the paused pane is not broadcast to other targets;
• Resume Sync for This Terminal joins it again.

Pause is not a transaction rollback. Characters and commands sent before pause may still execute remotely.

5.3 Production precautions

The target selector shows environment data, but interactive MultiExec does not create an approval dialog for each keystroke or command. It is live input synchronization, not the per-command Agent execution chain.

For production:

1. Validate a command first on one non-production or canary host.
2. Review IP/hostname, port, account, and environment for every target.
3. Use hostname, whoami, and pwd as the first read-only identity check and cross-check them with Stacio's endpoint.
4. Avoid multiline paste, interactive editors, and commands with timing dependencies.
5. Pause broadcast immediately when any target has different output.
6. Validate changes per target; one successful output never proves all targets.

5.4 Leave MultiExec

When closing a MultiExec tab, original terminals can return to independent tabs. After leaving synchronization, check for targets still running long commands and record partial success, failure, or unverified state.

6. Macros

A macro records actually submitted terminal commands to the local database and replays them in order to the current terminal.

6.1 Record a macro

1. Choose View > Macros or the toolbar macro entry point.
2. Click Start Recording.
3. Submit commands one by one in a local or remote terminal.
4. Return to Macros and click Stop Recording.
5. Name and save the macro.

Recording stores non-empty command lines that were actually submitted, not ordinary cursor movement or unsubmitted text. Common credential patterns are redacted when saving, but secrets still must not be entered in terminal commands.

6.2 Manage macros

The Macros panel supports:

• search by name or command;
• filter and group by group;
• rename and delete;
• import and export;
• view command count and updated time;
• enable or disable Confirm Before Run.

After importing a macro, inspect every command before any production replay. A macro file is executable content and should not be trusted solely because it came from a colleague or an older machine.

6.3 Replay a macro

1. Select the target terminal first.
2. Choose a macro in the panel.
3. Inspect its run preview and click Replay.
4. Stacio warns again when destructive commands are detected.
5. Observe output for every step and run targeted validation afterward.

Macros send in saved order with a default interval of about 300 ms per step; they do not wait for a previous command to finish. Do not use a macro to chain slow deployments, interactive input, steps that depend on earlier success, or database changes that must be serialized.

7. AI assistant

7.1 Configure a model

In Stacio > Settings > AI and Execution:

1. Add or choose a model provider.
2. Enter Base URL, model, and API key.
3. Test the connection and fetch a model list.
4. Configure terminal-context length.
5. Choose command-confirmation and execution mode.
6. Set automatic-allow and deny patterns as needed.

Model interfaces use an OpenAI-compatible channel. The API key is saved in the Stacio local credential store; model list and ordinary configuration stay in local settings.

7.2 Use the troubleshooting assistant

1. Select the correct current terminal.
2. Open View > AI Assistant.
3. In the target selector, verify terminal, directory, and environment.
4. Choose rule suggestions or model reasoning.
5. Enter a specific question, preferring read-only inspection and evidence.
6. Inspect each command card's target, command, risk, and explanation.
7. Approve, edit, skip, or reject the command.
8. Decide outcomes from real terminal output.

When Include Recent Terminal Output is enabled, the request contains recent terminal context up to its character limit. Avoid showing credentials, customer data, or unnecessary full logs in the terminal before sending.

7.3 Change tasks

The troubleshooting assistant's controlled orchestration requires:

• backup before a change;
• verification that backup location exists and is readable;
• minimum necessary change;
• targeted validation afterward;
• organized rollback on failure;
• a final report with backup, validation, and rollback information.

These gates reduce risk but do not replace least privilege, human approval, disaster recovery, or confirmation by the business owner.

8. Local Agent

Local Agent mode in the AI panel can detect and start local tools such as Codex, Claude, OpenCode, MiMo Code, ZCode, or Qwen Code. Each runs in an independent local workspace and is given the current terminal, remote directory, and a unified operational contract.

8.1 Start

1. Install the desired Agent CLI on the Mac and ensure Stacio can find it on PATH or a common installation path.
2. Select the remote terminal to operate.
3. Open the AI panel and switch to Local Agent.
4. Select a detected Agent from the tools menu.
5. Check the executable and remote bridge target in the status bar.
6. Submit the task in the native Agent session.

When Stacio cannot find a command, it reports that the tool is not detected or executable is missing. First prove the CLI starts from a local shell, then create a new Agent session.

8.2 Workspace tools

A local Agent workspace normally provides:

• stacio-sessions: list available terminals;
• stacio-remote "command": run remotely through Agent Bridge;
• stacio-agent: access lower-level Bridge subcommands;
• AGENTS.md, CLAUDE.md, QWEN.md, or general instruction files.

These wrapper commands are generated in a Stacio Agent workspace and are not guaranteed to be system-global commands. Local shell operations occur on the Mac; remote operations should go through Bridge so target selection, approval, and audit still apply.

8.3 Control boundary

Stacio can recognize risk, apply approval, and audit remote commands issued through Agent Bridge. It cannot guarantee that every local file operation, network request, or reasoning step of a third-party CLI is forced through the same state machine. Backup, validation, rollback, and final reporting for a local Agent are mainly constrained by the workspace operational contract.

See Agent Capabilities and Security for details.

9. Agent Bridge CLI

The Stacio package includes a local helper named stacio. While the main app runs, it starts a local-only Unix Domain Socket; copy its path from Settings > AI and Execution > Agent Bridge.

9.1 List targets

stacio agent sessions
stacio agent sessions --json

Get the current runtime ID before issuing later commands. Do not reuse an old runtime ID because it can change after terminal reconnect.

9.2 Run a command

stacio agent run --runtime <runtimeID> --command "uptime" --follow

You can also specify the current terminal or a saved session explicitly:

stacio agent run --target current --command "whoami"
stacio agent run --session <sessionID> --command "pwd" --follow

--follow streams status events until completion, failure, cancellation, pause, or takeover. --json is for another local program to parse; do not use string matching instead of JSON-state parsing.

9.3 Pause, cancel, and take over

Record a request ID from the event stream, then run:

stacio agent pause --request <requestID>
stacio agent cancel --request <requestID>
stacio agent takeover --request <requestID>

• Pause: stop the Agent from advancing while preserving current task state.
• Cancel: end a cancellable independent task.
• Take over: return control to the user terminal.

A successful control event only means Stacio accepted the request. Check whether the remote process actually stopped or requires manual cleanup.

9.4 Socket override

The default socket lives in the current user's Stacio Application Support directory. For specialized debugging, use:

stacio agent --socket /path/to/agent-bridge.sock sessions

or set STACIO_AGENT_SOCKET. Do not expose the socket to another user, a network share, or a container. When the main app is not running, the socket is stale, or the path does not match, the CLI reports Agent Bridge is not connected.

10. Approval, risk, and audit

10.1 Risk classification

AI and Bridge commands are classified as read-only, write, network, or destructive. Final execution also considers:

• global command-confirmation policy;
• session environment;
• per-session AI policy;
• automatic-allow patterns;
• deny patterns;
• the user's decision in the approval bar.

Deny takes precedence over automatic allowance, and production and Confirm Every Command increase approval requirements.

10.2 Audit records

Choose View > Diagnostics to view:

• MultiExec broadcast audit;
• AI/Agent request and execution state;
• request ID, runtime, target count, and send result;
• redacted command summary;
• application logs and import reports.

Audit-export count and whether application logs are included are controlled in Settings > Security. Audit supports tracing, not complete terminal recording, and it does not replace remote-system logs.

11. Recommended workflows

11.1 Read-only inspection across several hosts

1. Open each target terminal and record the IP/hostname, port, and account that Stacio displays.
2. Run hostname, whoami, and pwd, then cross-check them against endpoint and environment mark.
3. Start MultiExec.
4. Broadcast read-only commands such as whoami, uptime, and df -h.
5. Pause any target with different output.
6. Record outcomes per host instead of merging them into an ambiguous conclusion.

11.2 Enter a project directory after connecting

1. Put descriptive intent in the session Startup Command.
2. Restrict actual automatic action to a short Connection Script.
3. Use cd, pwd, and read-only status commands.
4. Confirm repeated execution is safe after reconnect.

11.3 AI-assisted change

1. Ask AI for read-only diagnosis first.
2. State the change target and completion standard.
3. Inspect backup command and location.
4. Approve every write command separately.
5. Observe real terminal output.
6. Validate configuration, service state, port, and business request.
7. Stop and roll back immediately when validation fails.

12. Work that is not suitable for automation

Do not directly use a Connection Script, interactive MultiExec, or a fixed-interval macro for:

• batch changes across production hosts with different versions or topology;
• database migration that must wait for a prior step;
• commands requiring interactive confirmation, OTP, or human judgment;
• wide deletion, recursive permission changes, or firewall rewrites;
• deployment without backup, rollback, or targeted validation;
• critical work that depends on unattended time triggers.

Use a dedicated automation system that offers idempotence, state checks, retry boundaries, key management, and centralized logs for these tasks; use Stacio for human verification or controlled troubleshooting.

13. Common questions

14. Completion standard

An automation task is complete only when all of these are true:

• target, environment, and account are confirmed;
• actual commands match approved content;
• every target has terminal output or an explicit failure state;
• pre-change backup is verified;
• post-change targeted check passes;
• partial success, cancellation, pause, and unverified items are explicitly recorded;
• the rollback method is executable;
• unnecessary MultiExec, Agent, tunnel, or external scheduled task is stopped.

See Security and Governance for policy and Remote Operations for operational validation.