← Plugins

sysadmin

Run shell commands on your servers over SSH

View source

plugin-sysadmin

A Stavrobot plugin that runs shell commands on your servers over SSH. Nothing is installed on the servers: the plugin uses the existing SSH daemon, and long-running commands keep running in the background while Stavrobot checks on them.

Prerequisites

  • Servers that the Stavrobot host can reach over SSH.
  • A POSIX sh on each server.
  • An account on each server to add the plugin's key to.

Installation

Tell Stavrobot to install https://github.com/stavrobot/plugin-sysadmin

Setup

The plugin creates its own SSH key when you install it and shows the public key in the install output. You can also ask Stavrobot for the key at any time.

Add the key to ~/.ssh/authorized_keys on each server, for the user you want Stavrobot to act as:

ssh-ed25519 AAAAC3...rest-of-key stavrobot-sysadmin

Optionally, restrict the key:

restrict,from="198.51.100.7" ssh-ed25519 AAAAC3...rest-of-key stavrobot-sysadmin
  • restrict disables port, agent and X11 forwarding and PTY allocation. The plugin needs none of these, so commands still work.
  • from= accepts the key only from the Stavrobot host's public IP. Omit it if that IP changes.

Then create a subagent, so that command output stays out of your main conversation. Tell Stavrobot something like:

Create a subagent named sysadmin with allowed_plugins ["sysadmin"] and no allowed_tools, with this system prompt: You administer my servers over SSH using the sysadmin plugin. Hosts: web1 = admin@203.0.113.10, db1 = ssh://root@203.0.113.20:2222. Do the task you are given, verify the result, then reply with a short summary of what you did and the outcome. Then save a memory: delegate all server administration to the sysadmin agent with send_agent_message and never call the sysadmin plugin directly.

To add a server later, ask Stavrobot to update the sysadmin agent's host list.

Configuration

None.

Tools

  • public_key: Returns the plugin's SSH public key.
  • run_command: Runs a shell command on a server and returns its output, or a job ID if it is still running.
  • wait_for_job: Waits for a running job and returns its output, or tells you it is still running.

Warning

Anything that can steer the agent can run commands on every server that trusts this key, as that user. This includes prompt injection from web pages or emails that Stavrobot reads. Use a dedicated account with only the privileges it needs.

Notes

  • The plugin trusts a server's host key on the first connection. If the host key changes later, the connection fails.
  • Commands keep running on the server even if the tool returns before they finish.
  • Commands run without a TTY, so interactive programs and password prompts do not work.