Remote Ops Plugin

Purpose

This plugin adds a focused remote execution tool for Agent Zero agents that need to inspect or maintain Linux hosts over SSH without building fragile SSH command strings by hand.

Phase 1 intentionally ships only one tool:

• ssh_execute

The goal is a small, dependable baseline for remote read-only diagnosis and approval-gated maintenance work.

Tool: ssh_execute

Use ssh_execute when an agent needs to run one concrete command on a remote host over SSH.

Supported arguments:

• host (required)
• user (required): SSH login user
• command (required): shell command body executed remotely via /bin/sh -s
• port (optional)
• key_path (optional): explicit private key path for non-default or project-scoped SSH keys
• timeout (optional)
• connect_timeout (optional)
• run_as_user (optional)
• working_directory (optional)
• known_hosts_mode (optional): strict, accept-new, or ignore

If the key is not available through the standard SSH agent or default ~/.ssh locations, pass key_path explicitly. Do not assume the runtime has already loaded a project-specific key.

If known_hosts_mode is omitted, the plugin default is accept-new. This is a pragmatic default for first-time connections: it accepts previously unseen host keys, but still protects against later host key changes. Use strict when host keys are already managed or pinned. Use ignore only when the user explicitly accepts the reduced host verification safety.

run_as_user behavior

run_as_user describes the target user for the remote command.

• If run_as_user is omitted or matches the SSH login user, the command runs directly without sudo.
• If run_as_user is root, the tool internally executes the command with sudo -n -- /bin/sh -s.
• If run_as_user differs from the SSH login user, the tool internally executes the command with sudo -n -u <user> -- /bin/sh -s.

This means sudo is required only when the target user differs from the SSH login user. The SSH login user must have the necessary non-interactive sudo permission, otherwise the tool fails with a clear error.

run_as_user is a convenience and safety feature so the agent does not need to hand-build sudo -u ... strings inside command.

Operational notes

• The tool sends the command body to the remote shell through standard input.
• This reduces quoting and encoding problems compared to embedding complex shell fragments directly into one SSH command string.
• The tool returns structured JSON with exit code, stdout, stderr, truncation flags, and transport-level error classification.
• The tool does not change the server admin agent's approval rules. Mutating actions still require explicit user approval first.

Examples

Read-only inspection as the SSH login user:

{
  "tool_name": "ssh_execute",
  "tool_args": {
    "host": "example.org",
    "user": "ops",
    "key_path": "/path/to/id_ed25519",
    "command": "uname -a && id",
    "timeout": 20
  }
}

Read-only inspection as root:

{
  "tool_name": "ssh_execute",
  "tool_args": {
    "host": "example.org",
    "user": "ops",
    "key_path": "/path/to/id_ed25519",
    "command": "systemctl status nginx --no-pager",
    "run_as_user": "root",
    "timeout": 20
  }
}

Application command as a service user:

{
  "tool_name": "ssh_execute",
  "tool_args": {
    "host": "example.org",
    "user": "ops",
    "key_path": "/path/to/id_ed25519",
    "command": "php artisan cache:clear",
    "run_as_user": "www-data",
    "working_directory": "/var/www/app",
    "timeout": 30
  }
}

Scope intentionally excluded from Phase 1

• persistent SSH sessions
• deployment sync helpers
• symlink management helpers
• service-specific health-check DSLs
• custom WebUI components