Ctrlk
Download

AI Agents for Server Automation (Codex, Claude Code, OpenCode)

Connect Codex CLI, Claude Code, OpenCode, or any MCP-compatible AI agent to Tempest's MCP server to automate SSH operations, server maintenance, and interactive terminal tasks without writing scripts.

Tempest ships a built-in MCP (Model Context Protocol) server that gives any compatible AI agent a full SSH terminal. The agent can open sessions to your saved servers, type commands, read the rendered screen, drive interactive TUIs (htop, vim, dialog), and close connections — all over the same tool protocol that Claude Desktop, Codex CLI, and OpenCode understand natively.

No shell scripts. No Ansible playbooks for one-off tasks. Just describe what you want, and the agent handles the keystrokes.

How it works

┌─────────────┐      MCP (stdio / HTTP)      ┌──────────────────────┐
│  AI agent   │ ←────────────────────────→  │  tempest mcp server  │
│ (Codex CLI, │    tool calls & results      │                      │
│  Claude,    │                              │  ssh_connect         │
│  OpenCode…) │                              │  feed_from_terminal  │
└─────────────┘                              │  feed_from_session   │
                                             │  list_ssh_servers    │
                                             │  … (15 tools total)  │
                                             └──────────┬───────────┘
                                                        │ libssh2 / PTY
                                                        ▼
                                             ┌──────────────────────┐
                                             │   your remote host   │
                                             └──────────────────────┘

The MCP server runs locally on your machine and acts as the SSH client. Credentials stay in your encrypted Tempest vault — the AI only ever sees server names and terminal output, never passwords or private keys.

Setup

This page focuses on what the agent can do once it's connected. For step-by-step installation in Claude Code, Codex CLI, Claude Desktop, Cursor, VS Code, Zed, OpenCode, and other MCP clients — plus prerequisites, transport options, the full tool reference, and troubleshooting — see Install Tempest MCP Server in Claude Code, Codex, Cursor & More.

The short version: claude mcp add tempest -- tempest mcp (Claude Code), or the equivalent config entry in your client. Then ask the agent "List my saved SSH servers" to confirm it's wired up.

Practical examples

Check disk usage across all your servers

Prompt:

List my saved SSH servers, connect to each one, run df -h, and give me a table of filesystem usage. Flag any filesystem over 80%.

The agent will:

  1. Call list_ssh_servers to enumerate your vault.

  2. For each host, call ssh_connect_saved → feed_from_terminal ("df -h\r") → feed_from_session to read the output.

  3. disconnect when done.

  4. Summarize results in a markdown table.

Restart a failing systemd service

Prompt:

SSH into my web-01 server and restart the nginx service. Show me the journal output after restart and confirm it's running.

The agent will:

  1. list_ssh_servers → pick web-01 → ssh_connect_saved.

  2. feed_from_terminal: "sudo systemctl restart nginx\r".

  3. feed_from_session to read any password or error prompts; respond if needed.

  4. feed_from_terminal: "sudo journalctl -u nginx -n 50 --no-pager\r".

  5. feed_from_session → paste output back to you.

  6. disconnect.

Investigate a full disk

Prompt:

My db-02 server is reporting a full disk. SSH in and find what's taking up space under /var.

The agent runs the command, reads the screen, drills down into the largest directory, and proposes what to clean up — all without you touching a terminal.

Drive an interactive TUI

Prompt:

Open htop on my dev server and tell me which process is consuming the most CPU right now.

The agent:

  1. ssh_connect_saved → dev server.

  2. feed_from_terminal: "htop\r".

  3. Waits ~300ms, then calls feed_from_session.

  4. Reads the rendered htop grid — process list, CPU bars, memory gauges — and summarizes the top consumer.

  5. Sends "q" to quit, then disconnect.

feed_from_session returns the terminal screen as rendered (cursor position, alternate-screen flag, styled text with color annotations). The agent sees exactly what you would see.

Batch deploy a config change to multiple servers

Prompt:

Update /etc/sysctl.conf on all my "production" group servers to set net.core.somaxconn=4096, then reload without rebooting.

The agent opens sessions in sequence (or asks if you want parallel), runs echo / tee / sysctl -p, reads each server's output, and reports which hosts succeeded.

Tips for writing effective prompts

Name your servers clearly. The agent calls list_ssh_servers and picks by name. A server named db-primary-us-east is easier to reason about than srv-04.

Prefer saved servers over ad-hoc credentials. ssh_connect_saved keeps credentials out of the conversation entirely — the vault decrypts locally. If you must use ssh_connect with a password, the password will appear in the agent's tool call log.

Ask the agent to disconnect when done. Sessions leak resources if left open. A prompt like "clean up all connections when finished" is enough.

For long-running commands, tell the agent to wait before reading: "Run the backup script and give it 60 seconds before checking the output." The agent can send the command, tell you it's waiting, then call feed_from_session after the delay.

Auditing the agent at runtime

Most agent CLIs show tool calls before executing them — Codex CLI's --approval-policy auto vs. cautious, Claude Code's confirmation prompt, Cursor's per-tool approval. Review the feed_from_terminal calls before approving, especially for destructive operations (rm, systemctl stop, DROP TABLE). For broader credential and transport-level security, see the Security notes in the installation guide and Reset Your Tempest Password for vault key rotation.

See also

PreviousTempest AI AssistantNextInstall Tempest MCP Server in Claude Code, Codex, Cursor & More

Last updated