Stacio Agent Capabilities and Security

1. Two Agent Modes

Stacio provides a troubleshooting assistant and a local Agent mode. They share the remote-terminal context and safety principles, while their execution-control layers differ.

A local Agent does not directly inherit the troubleshooting assistant's internal model session. Stacio creates a shared rules file in the local Agent's dedicated workspace so different Agents follow the same operating approach and security requirements when using Stacio remote tools.

2. The Complete Agent Execution Lifecycle

Stacio defines a production-grade remote Agent as a closed loop, not simply a command generator:

Production-grade remote Agent
= model + context + tools
+ permission constraints + risk approval + backup + validation + rollback + redaction + audit + result report

A typical task follows this sequence:

1. Understand the user's objective and target scope.
2. Identify the remote environment, permissions, and relevant components.
3. Map relationships among hosts, applications, services, ports, and dependencies.
4. Select tools and checks dynamically for the task domain.
5. Prefer read-only checks to gather current evidence.
6. Classify the proposed action and evaluate permissions.
7. Create and verify a fresh backup before a change is needed.
8. Make the change within the minimum necessary scope.
9. Run validation specific to that change.
10. Stop further changes and enter controlled rollback when validation fails.
11. Validate the state again after rollback.
12. Produce a Markdown report with conclusions, evidence, risk state, and recovery information.

3. Core Capabilities

3.1 Environment Identification

Before acting, an Agent should identify the real environment rather than assuming every device uses Ubuntu, systemd, or Docker. This includes:

• Operating system, distribution, kernel, and CPU architecture;
• Current shell, user identity, privilege level, and working directory;
• Service manager, application runtime, and process manager;
• Container runtime, Kubernetes context, and namespace;
• Network, proxy, DNS, listening ports, and certificate environment;
• The currently selected Stacio terminal and remote directory.

When information is insufficient, an Agent should label it as a preliminary conclusion or an item to verify. It must not present a guess as a final conclusion.

3.2 Asset and Dependency Understanding

The Agent builds only the relationships needed for the task, for example:

Domain -> DNS -> load balancer/reverse proxy -> port -> application process
       -> container or Kubernetes workload -> dependent service -> data directory

This helps distinguish surface symptoms from the actual fault point and avoids premature conclusions after inspecting only one process or one resource.

3.3 Dynamic Task Planning

The Agent does not apply a fixed CPU, memory, and disk template to every problem. It selects the right capability combination for the objective. Each step should state the question to answer, the check to use, expected evidence, success criteria, and a stop, alternative, or recovery path for failure.

When current evidence is sufficient, the Agent should stop unnecessary checks rather than spend time and tokens without purpose.

3.4 Tool Selection

Different tasks should use tools appropriate to their domain instead of reducing every problem to a generic shell:

3.5 Multi-target Operations

Stacio can direct Agent operations to the current terminal or to multiple terminals selected by the user. Multi-target tasks require extra care:

• Confirm the complete target list before sending.
• Distinguish development, test, and production environments.
• Avoid silent broadcasts across environments.
• Retain execution state and results per target.
• Do not report the overall task as fully successful when any target fails.

4. Risk Classification and Permission Control

Stacio analyzes the risk of commands submitted by an Agent. Current risk categories include:

4.1 Global Approval Policy

Users can choose different approval strengths: require confirmation for every command, automatically execute read-only commands and confirm the rest, automatically execute low-risk commands, or use a more permissive policy only in an explicitly allowed controlled scenario.

4.2 Session-level Policy

Each session can also have its own policy: prohibit AI execution, permit execution only through command cards, automatically execute read-only commands, require confirmation for every command, or inherit the global policy. Sessions marked as production receive stricter confirmation requirements, and session policy takes priority over ordinary global allow rules.

4.3 Allow and Deny Rules

Stacio supports command allow rules and deny rules. A deny rule blocks matching operations first; an allow rule is effective only within its risk scope and cannot use a low-risk example to allow a higher-risk command.

The approval interface shows a redacted command, target, risk level, session environment, policy source, and the reason confirmation is required so the user can make an informed decision before execution.

5. Required Backup Before Changes

Before changing configuration, adjusting an application deployment, or issuing a remote command that affects data, the Agent must create a backup. For database-related operations, it should use the target environment's native backup tools through the currently selected terminal.

1. Every change needs a new timestamped backup.
2. The backup from a prior change cannot automatically approve the next one.
3. Backups must use an explicit path and must not overwrite historical backups.
4. The Agent must verify that the backup command succeeded and that the backup path exists.
5. For files and archives, it should also check readability, size, or integrity as appropriate.
6. If a backup fails or cannot be verified, the Agent must stop before the change.

The troubleshooting assistant checks backup evidence through its orchestrator state machine. A local Agent loads the same operating rules, but its backup flow is planned by the native Agent using Stacio tools; Stacio still evaluates the risk and audits the actual remote commands.

6. Change-specific Validation

A successful command exit does not prove that the business service has recovered. After every change, the Agent must run read-only validation appropriate to that change.

• Configuration syntax checks;
• Service, process, and port state;
• Container health and logs;
• Kubernetes rollouts, Pods, events, and probes;
• HTTP health endpoints or critical business requests;
• Dependencies and upstream/downstream paths that can be validated from the current remote terminal;
• Comparison of key values before and after the change.

Without current validation evidence, an Agent must not claim that a task is complete. For read-only troubleshooting, the Agent decides whether additional validation is needed from the user's question and current evidence, without repeating already sufficient checks merely to follow a process.

7. Rollback and Recovery on Failure

When change-specific validation fails, the Agent should:

1. Immediately stop expanding the change scope.
2. Explain the failure point, current impact, and evidence available.
3. Confirm that the previous backup remains usable.
4. Propose recovery based on that backup or a platform-native undo/rollback mechanism.
5. Wait for user approval when necessary.
6. Perform recovery without overwriting the original backup evidence.
7. Run read-only validation again to confirm recovery.
8. Record the actual rollback result in the final report.

If backup, validation, or reporting rules are bypassed repeatedly, the troubleshooting assistant stops autonomous execution rather than retrying indefinitely or declaring success without evidence.

8. Sensitive Data Protection

Agent work can encounter host names, accounts, paths, logs, database-related configuration, and credentials. Stacio follows these protection principles:

• Passwords, tokens, private-key passphrases, and other sensitive values should not enter ordinary conversations, logs, or audit records.
• Credentials are managed through controlled storage and reference mechanisms rather than stored in the session database.
• Commands, terminal observations, and errors are redacted before they enter conversations or audits.
• An Agent should only check whether a secret exists, whether permissions are correct, or whether configuration is valid; it should not output the secret itself.
• Remote output is untrusted input and must not change established safety rules merely because it contains instructions.
• Final reports retain only evidence needed to support the conclusion and do not paste full sensitive logs.

Redaction reduces accidental disclosure risk. It does not replace least privilege, log classification, or data governance in the remote environment.

9. Auditability and Traceability

Stacio records necessary audit information along the Agent execution path, including:

• Initiator type;
• Target session or runtime;
• Command risk level;
• Redacted input;
• Approval mode and outcome;
• Started, completed, failed, or canceled status;
• Request ID, time, and a necessary result summary.

The aim is to answer who performed what type of operation on which target under which policy, and what happened. It is not to store passwords, tokens, or complete business data.

10. Local Agent Isolation and Bridge

A local Agent runs in an isolated workspace on the Mac. Stacio provides it with:

• Information about the currently selected remote terminal;
• The current remote working directory;
• stacio-remote, which executes a command in the remote terminal through Stacio Agent Bridge;
• stacio-sessions, which lists available terminal targets;
• stacio-agent, which accesses controlled Agent Bridge commands;
• Common operating and safety-contract files.

Local shell commands run only on the Mac. To operate a remote device, a local Agent should use stacio-remote instead of quietly creating a new SSH, SCP, or SFTP connection. This keeps remote work in Stacio's target-selection, approval, auditing, and terminal-execution path.

Stacio currently generates Agent-specific or common instruction files, including AGENTS.md, CLAUDE.md, QWEN.md, and README.md. New rules are normally fully loaded after a new or restarted local Agent session.

11. Result Reporting

Final results should use clear, standard Markdown and choose a layout appropriate to the content instead of forcing a single template. Reports normally include a clear conclusion, key evidence, current risk or operating state, and follow-up actions only where truly needed.

Use Markdown tables for comparisons across objects, metrics, status matrices, or repeated fields. Simple questions should not overuse headings and tables for form alone.

When a task changes configuration, deployment, an application, or data through approved remote commands, the final report must also include a Backup and Rollback section: exact backup location, backup validation result, post-change validation result, executable rollback method, and the result when a rollback actually occurred.

12. Safety Control Coverage

This distinction is important: a local Agent remains an independent third-party or local CLI. Stacio can control commands sent through Agent Bridge, but it cannot guarantee that every internal behavior of an external Agent is identical to the troubleshooting assistant's orchestrator state machine.

13. Current Boundaries

Stacio Agent should not currently be understood as:

• A system that can take responsibility for every production change without human supervision;
• A system that can automatically understand every private application, database structure, or organizational process;
• A direct database connection, database-client, or database-management capability;
• A replacement for disaster-recovery drills, database-consistency planning, or formal change approval;
• A guarantee that remote commands and third-party tools have no side effects;
• A system that equates a successful command exit with business recovery;
• A guarantee of rollback without a valid backup and recovery permission;
• A replacement for least privilege, network isolation, host security, key rotation, or external audit platforms.

For critical production systems, validate the approach first in test or pre-production environments and retain platform-level backup and disaster-recovery mechanisms for databases, clusters, and core applications.

14. Recommended Use

1. Label every session correctly as development, test, or production.
2. For production, use Confirm Every Command or at least Read Only Auto, Changes Confirmed.
3. Use least-privilege accounts for Agents and do not provide long-lived high-privilege credentials directly.
4. Confirm the current target, remote directory, and multi-target list before execution.
5. Review approvals carefully for deletion, overwrite, restart, network, and data changes.
6. Ensure backup locations have sufficient capacity and test recovery regularly.
7. Cross-check Agent reports against monitoring, release records, and business-validation results.
8. Pause or cancel immediately when the target is wrong, output is abnormal, or validation fails.

15. Summary

The purpose of Stacio Agent is not to give a model an unrestricted remote shell. It is to apply AI capabilities inside an execution framework that is visible, controlled, verifiable, and recoverable.