Servonaut

Your servers. Your terminal. Your AI agent. One TUI.

Manage AWS, Hetzner, OVH, and custom servers from one terminal — with a built-in AI assistant and MCP server.

Quick Install

Linux / macOS:

curl -sSL https://raw.githubusercontent.com/zb-ss/servonaut/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/zb-ss/servonaut/master/install.ps1 | iex

Or install directly via pipx / pip:

pipx install servonaut

Manual install from source:

git clone https://github.com/zb-ss/servonaut.git
cd servonaut
pipx install .

Set up with an AI agent

Prefer to let an AI agent do the whole thing? Paste this prompt into Claude Code, Cursor, or any coding assistant — it installs Servonaut, generates the config, and walks you through AWS / SSH / bastion / custom-server / AI-provider setup plus the MCP server.

Install and configure Servonaut, a TUI for managing servers (AWS EC2, OVHcloud, Hetzner Cloud, and custom SSH servers).

1. Install with all optional features: `pipx install 'servonaut[all]'`
   (bundles the MCP server + OVH/Hetzner SDKs + keyring; AI log analysis needs no extra. Use plain `pipx install servonaut` for a minimal install.)
2. Run `servonaut` once to generate ~/.servonaut/config.json
3. (Optional) If I have a Servonaut account, run `servonaut login` to unlock the hosted features: Servonaut AI (chat with my fleet, no local API key), config sync across machines, Memory Sync, and proactive monitoring (Findings). Servonaut works fully offline against my own credentials if I skip this.
4. Read ~/.servonaut/config.json and help me configure:
   - AWS regions to scan (default scans all, set `regions` array to limit)
   - Default SSH username (`default_username`, default "ec2-user")
   - Cache TTL (`cache_ttl_seconds`, default 3600)
   - Terminal emulator if not auto-detected (`terminal_emulator`)
5. If I use bastion/jump hosts, help me set up `connection_profiles` and `connection_rules`
6. If I have non-AWS servers, help me add them to `custom_servers`
7. If I use OVHcloud or Hetzner Cloud, help me add the API credentials so those instances merge into the fleet
8. For AI log analysis or chat with my own model (instead of Servonaut AI), help me configure `ai_provider` (openai/anthropic/gemini/ollama)
   - Each provider has its own key field (`openai_api_key`, `anthropic_api_key`, `gemini_api_key`, `ollama_api_key`); local Ollama needs none
   - Key fields support `$ENV_VAR` and `file:~/.secrets/key` syntax so secrets stay out of the config file
9. Install the MCP server into my coding agent: `servonaut --mcp-install claude` (or `cursor`, `windsurf`, `opencode`, `vscode`, `codex`, `agy`, `gemini`, `all`)
10. (Optional) To let AI agents/teammates reach this machine over the relay — and to run proactive Findings scans — start it with `servonaut connect`

After setup, launch with `servonaut` and walk me through the key features, including the Findings inbox if I enabled the hosted features.

Screenshots

Instance list — AWS, Hetzner, OVH, and custom servers merged into one view

Sidebar reveals Fleet Memory, Memory Sync, Secrets, Settings, and per-provider management for OVH and Hetzner

Built-in AI assistant with MCP server integration — chat with local providers or hosted Servonaut AI

CloudWatch log browsing with Top IPs analysis, geolocation, and abuse scoring

Ban/unban IPs via WAF, Security Groups, or NACLs with audit trail

All screenshots and the launch video were recorded with --demo active, which replaces real IPs, ARNs, paths, and secrets with safe fake equivalents. See docs/demo-mode.md for what is redacted and how to use it.

Features

Badges: Solo+ = included with paid Solo/Teams plans.

Core & connectivity

• Interactive TUI — mouse + keyboard, powered by Textual.
• Multi-provider fleet — AWS EC2, OVHcloud (dedicated / VPS / Public Cloud), Hetzner Cloud, and custom servers from any provider (DigitalOcean, on-prem, …) — listed and searchable in one view across all regions.
• Per-instance dashboard — click a server for a Server Actions view: a memory snapshot (OS, disk, web stack, databases, runtimes, containers) plus an opt-in live resource monitor (L — CPU / RAM / load / disk / uptime, polled only while open).
• SSH & SCP — one-key SSH in a new terminal window (auto-detected emulator); upload/download files and directories.
• Run remote commands — overlay panel with real-time streaming output, history, and saved favorites.
• Remote file browser — interactive file-tree navigation, inline in the dashboard or full-screen.
• Real-time log viewer — stream logs via tail -f with pause, search, and log switching.
• Robust SSH — bastion / jump-server (ProxyJump / ProxyCommand), keepalives on by default (tunable), per-host extra_ssh_options for legacy boxes, and key auto-discovery.

Cloud provider management

• OVHcloud — OVH → ⚙ Manage: create / start / stop / reboot / delete (Cloud / VPS / dedicated), a region-first create wizard with API-backed pricing, plus DNS, IP blocks & failover IPs, snapshots, block storage, and billing.
• Hetzner Cloud — Hetzner → ⚙ Manage: full lifecycle + project SSH-key registry, with an equivalent CLI (servonaut hetzner …). Auto-registers new servers. → docs

Observability & security

• Proactive monitoring — Findings (Solo+) — cloud-side detectors surface fleet issues (disk, failed services, slow queries, credential-scanning cross-referenced with fail2ban, container health, TLS expiry, pending updates) as triageable cards, with gated one-click remediation (server-signed preview → human confirm → verb-allowlisted executor; block IP or renew a cert). → guide
• CloudWatch Logs browser — log groups with Top-IPs analysis, IP geolocation, and AbuseIPDB lookups.
• CloudTrail browser — AWS CloudTrail events with region / time / event / user filters.
• IP ban manager — ban IPs via AWS WAF, Security Groups, or NACLs, with an audit trail.
• Keyword server scanning — search file contents across instances.

AI

• Servonaut AI (Solo+) — hosted AI gateway; chat with your fleet with no local API key. The model can tail logs, run commands (with confirmation), and triage incidents over the relay — credentials and SSH keys never leave the CLI. Quota inline / servonaut ai quota.
• Bring your own key — OpenAI / Anthropic / Gemini / Ollama keys configured per-provider in Settings → AI Provider (local Ollama needs none). All coexist with Servonaut AI, switchable per-session.
• Built-in AI chat — LLM assistant with tool-calling against your instances (the same MCP tool surface below).
• AI log analysis — analyze logs with OpenAI, Anthropic, Gemini, or Ollama, with cost estimation.
• Voice — dictate into the chat panel with ctrl+t, have replies read aloud, or go fully hands-free with conversation mode (ctrl+n): the mic stays open between turns and replies are spoken — with optional barge-in (headphones mode) to interrupt a reply by talking over it. Transcription and speech synthesis run entirely on your machine, so audio never leaves the workstation. Opt-in — nothing is downloaded until you enable it in Settings. → docs

Memory & secrets

• Server memory — persistent per-server cache of OS / runtime / service / web-stack / log / database / container / git / disk facts; optional background fleet auto-scan. → docs
• Memory Sync (Solo+) — end-to-end-encrypted backup of fleet memory to servonaut.dev (X25519 + AES-256-GCM, your passphrase), with drift detection, cross-device history, and optional auto-sync. ☁ Memory Sync in the sidebar.
• Database credential vault (Solo+) — scan a server for the DB credentials its apps already use, store the password in your secret vault under a per-site label, and let the db_* tools resolve it by name — no password in config or agent context. → docs

Agents & automation (MCP)

• MCP server — ~80 tools for Claude Code, Cursor, Windsurf, etc.: instance ops, AWS / Hetzner / OVH lifecycle, S3, log analysis & IP banning, Docker inspection, system-health probes, SSH-key CRUD, memory queries, and an authenticated REST proxy — behind a three-tier guard (readonly / standard / dangerous) with a JSONL audit trail. → details below
• MCP relay — servonaut connect (or TUI autostart) holds a Mercure SSE connection open so agents and team-mates can dispatch tool calls to this machine. Tokens never leave the CLI.
• Servonaut Cloud account — optional servonaut login unlocks config sync across machines and the MCP relay.
• Config sync — client-side-encrypted snapshots of your config.json synced via servonaut.dev, paired with a passphrase you control.

Convenience

• Instance caching — stale-while-revalidate for fast startup.
• Auto-update — startup check + one-click update (servonaut --update).
• Desktop shortcut — servonaut --install-desktop (Linux/macOS).
• Fully configurable — everything in ~/.servonaut/config.json.

Prerequisites

• Python 3.10+
• AWS CLI configured (~/.aws/credentials and ~/.aws/config)
• SSH client (standard on Linux/macOS, OpenSSH on Windows)
• pipx for isolated installation (recommended)

Your AWS credentials need ec2:DescribeInstances and ec2:DescribeRegions permissions. Additional permissions needed for optional features:

Feature	Required Permissions
CloudTrail browser	cloudtrail:LookupEvents
IP ban (WAF)	wafv2:GetIPSet, wafv2:UpdateIPSet
IP ban (Security Groups)	ec2:AuthorizeSecurityGroupIngress, ec2:RevokeSecurityGroupIngress, ec2:DescribeSecurityGroups
IP ban (NACLs)	ec2:CreateNetworkAclEntry, ec2:DeleteNetworkAclEntry, ec2:DescribeNetworkAcls
CloudWatch Logs	logs:DescribeLogGroups, logs:FilterLogEvents
OVHcloud (optional)	OVH API credentials — 3-key (application key / secret / consumer key) or OAuth2. Set up via servonaut --setup-ovh or in Settings.

Getting Started

servonaut

That's the whole interface. The TUI is the primary and recommended way to use Servonaut — every feature (fleet view, SSH, remote commands, logs, IP banning, AI chat, server memory, provider management) is reachable from the sidebar, with full mouse and keyboard support.

A few flags you may want on day one:

servonaut --update                # Check for updates and upgrade
servonaut --install-desktop       # Create desktop shortcut (Linux/macOS)
servonaut --setup-ovh             # Guided OVHcloud credential setup
servonaut --debug                 # Verbose logging to stderr

Headless & automation: every major feature also has a scriptable CLI (servonaut connect, servonaut memory, servonaut ai, servonaut hetzner, servonaut secrets) for CI runners, cron jobs, and boxes without an interactive session — see the CLI Reference. Wiring up an AI agent instead? Jump to MCP Server for AI Agents.

Keyboard Shortcuts

Context	Key	Action
Main Menu	U	Update Servonaut (when update available)
Global	Q	Quit
Global	?	Help screen
Global	Escape	Go back / close
Global	Ctrl+P	Command palette — "Go to …" jumps to any sidebar section from the keyboard
Instance List	/	Focus search
Instance List	R	Force-refresh from AWS
Instance List	S	SSH to selected instance
Instance List	B	Browse remote files
Instance List	C	Run command overlay
Instance List	T	SCP transfer
Instance List	Y	Copy IP to clipboard
Server Actions	L	Toggle the live resource monitor
Server Actions	1–8	Run the numbered action (Browse, Command, SSH, …)
Server Actions	Esc	Close inline view, or go back
Global	F2	Toggle AI chat panel
Anywhere	Mouse drag	Select text (auto-copies to clipboard)
Anywhere	Ctrl+C	Copy selected text
Command Overlay	Ctrl+C	Stop running command
Command Overlay	Ctrl+R	Command picker (saved + recent)
Command Overlay	Ctrl+S	Save command to favorites
Command Overlay	Up/Down	Command history
Log Viewer	P	Pause/resume streaming
Log Viewer	C	Clear output
Log Viewer	F	Find/search in output
Log Viewer	L	Switch log file

What You Can Do

The TUI opens to a unified instance list (AWS + OVH + Hetzner + custom servers in one searchable table). The collapsible left sidebar groups everything else by purpose:

Core

• 📋 Instances — search and SSH the unified fleet
• 💻 Custom Servers — add / edit / remove non-AWS servers (DigitalOcean, on-prem, etc.)
• 🔑 SSH Keys — configure default and per-instance keys

Logs & Security

• 📊 CloudWatch — browse AWS log groups with Top IPs analysis, action filter (All/Allowed/Blocked), IP geolocation, AbuseIPDB lookup
• 🔒 IP Ban Manager — ban IPs via WAF, Security Groups, or NACLs
• 🔍 CloudTrail — audit AWS API activity with filters

Tools

• 🧠 Fleet Memory — scan / refresh / inspect the AI-queryable fact cache, with an optional scheduled background auto-scan (bulk scans run in the background and survive leaving the panel)
• ☁ Memory Sync — encrypted backup of fleet memory across devices (Solo+)
• 🛡 Findings — proactive-monitoring inbox: scan, review, and triage server-detected issues fleet-wide (Solo+; Free shows an upgrade card)
• 🔄 Sync Config — encrypted config snapshots (Solo+)
• 🔧 Settings — configuration, scan rules, AI provider, AbuseIPDB key

OVH (visible when configured)

• ⚙ Manage — table of OVH instances with state-aware lifecycle toolbar (Create / Start / Stop / Reboot / Delete)
• 🔑 SSH Keys — project-level SSH key registry (the one the create wizard injects from)
• DNS Zones · IP Management · Block Storage · Billing

Hetzner (visible when configured)

• ⚙ Manage — table of Hetzner servers with full lifecycle toolbar (Create / Power on / Shutdown / Reboot / Delete)
• 🔑 SSH Keys — Hetzner Cloud project SSH key registry

Account

• Login · Teams · Bug Reports

Server Actions — clicking any instance row opens a per-instance dashboard: the detail pane shows the server's identity, a memory snapshot, and an opt-in live resource monitor (L), and the action rail covers:

• Browse Files (inline) · Run Command · SSH Connect · SCP Transfer
• View Scan Results · View Logs (tail -f) · AI Analysis · Findings (F)
• Ban IP · Manage/Verify SSH Ref

The SSH Ref editor pairs with a Bitwarden vault — pick an SSH key from a list instead of pasting a UUID, or import keys straight from ~/.ssh (passphrase-protected included), so a machine with no local keys can still connect. The TUI, CLI, and MCP agents all resolve the key from your vault at connect time (Solo+). → docs

Command history persists across sessions — Ctrl+R to search history and saved commands, Ctrl+S to save favorites.

Instance Caching

Scenario	Behavior
First launch (no cache)	Fetches from AWS with progress indicator
Restart within TTL (default 1h)	Instant load from cache
Restart after TTL	Shows stale data immediately, refreshes in background
Press R	Force-refresh from AWS

Configuration

All configuration lives in ~/.servonaut/config.json, created automatically on first run.

See Configuration Guide for the full reference including connection profiles, custom servers, scan rules, and match conditions.

SSH keepalives: all connections send keepalives by default so long or idle agent-driven sessions don't get dropped. Tune globally via the ssh block in config.json (server_alive_interval, server_alive_count_max, tcp_keepalive, connect_timeout).

Legacy / special-case SSH hosts: connection profiles and custom servers both accept an extra_ssh_options array that appends arbitrary -o KEY=VALUE flags per host — use it to talk to ancient OpenSSH boxes (HostKeyAlgorithms=+ssh-rsa), override keepalives, or set connect timeouts without weakening your global SSH defaults. See Per-host SSH tuning.

Secrets: API keys in config.json support $ENV_VAR and file:~/.secrets/key syntax so the config file stays secret-free. You can also create ~/.secrets/servonaut.env with KEY=value pairs — loaded automatically on startup.

Optional Dependencies

# MCP server for AI agents
pipx inject servonaut mcp
# or: pip install 'servonaut[mcp]'

# Hetzner Cloud / OVHcloud provider SDKs
pip install 'servonaut[hetzner]'
pip install 'servonaut[ovh]'

# Voice — all processed locally, nothing sent to a speech service
pip install 'servonaut[voice]'            # voice input, batch engine
pip install 'servonaut[voice-streaming]'  # voice input, live text as you speak
pip install 'servonaut[voice-output]'     # spoken replies / conversation mode

# Install everything
pip install 'servonaut[all]'

Voice also needs the PortAudio system library (sudo apt install libportaudio2, brew install portaudio) and one-time model downloads, both surfaced in Settings → AI → Voice Input. See docs/voice.md.

AI log analysis (OpenAI, Anthropic, Gemini, Ollama) needs no extra install — httpx ships as a base dependency.

MCP Server for AI Agents

This section is for wiring up AI agents (Claude Code, Cursor, Windsurf, …) — not day-to-day interactive use. If you're a human operating your fleet, the TUI above is the recommended interface.

Servonaut includes an integrated MCP server that exposes tools to AI agents like Claude Code:

# Auto-install into a coding agent
servonaut --mcp-install claude     # Claude Code
servonaut --mcp-install cursor     # Cursor
servonaut --mcp-install windsurf   # Windsurf
servonaut --mcp-install opencode   # OpenCode
servonaut --mcp-install vscode     # VS Code Copilot
servonaut --mcp-install codex      # Codex CLI
servonaut --mcp-install agy        # Antigravity CLI
servonaut --mcp-install gemini     # Gemini CLI
servonaut --mcp-install all        # All of the above

# Run MCP server manually (stdio transport)
servonaut --mcp

Re-running an installer updates only Servonaut's launch command and required environment forwarding. Other MCP servers and user-owned settings such as timeouts, trust, tool filters, and custom environment entries are preserved. Secret values are never copied into agent configuration: supported clients use references, variable-name allowlists, or inherited environment to supply SSH/Bitwarden state, AWS credentials, Servonaut endpoints, and $ENV_VAR references found in the local Servonaut config. Invalid agent JSON is refused instead of overwritten, and config writes are atomic without replacing symlinked dotfiles.

SSH-backed MCP tools first use the configured local or vault key. If that key cannot authenticate and SSH_AUTH_SOCK was forwarded, Servonaut retries once using the agent without forcing the configured identity. Authentication failures are returned and audited as failures, never as successful tool calls.

Agent-only / headless install

You don't need the TUI to use Servonaut as an agent toolbox. The MCP server runs fully headless — servonaut --mcp never loads the terminal UI (this is enforced by a regression test), so you can install it on a server or CI box purely as an MCP backend for your coding agent:

pipx install 'servonaut[mcp]'
servonaut --mcp-install claude   # or cursor, windsurf, opencode, vscode, codex, agy, gemini, all

Configure credentials and servers the same way as a TUI install ( ~/.servonaut/config.json, $ENV_VAR / file: secret syntax — see Configuration Guide). For Servonaut Cloud features (relay, config sync, hosted AI), servonaut login runs the device-flow sign-in fully headless — approve from a browser on any device. Everything an agent does goes through the same guard levels and is logged to ~/.servonaut/mcp_audit.jsonl.

SSH keys from Bitwarden (no keys on the box). If your instances have a Bitwarden SSH ref saved, the SSH-backed tools (run_command, get_logs, transfer_file, …) resolve the private key from your vault at connect time instead of needing it in ~/.ssh — so an agent on a fresh server or CI box can connect with no local keys at all. Because a headless process can't prompt for your master password, unlock the vault once and export the session into the environment the MCP server (or servonaut connect) runs in:

export BW_SESSION=$(bw unlock --raw)   # unlock once; stays valid until you `bw lock` or the shell exits
servonaut --mcp                         # child inherits BW_SESSION

The key is written to a private, 0600 temporary file only for the duration of each command and deleted immediately after. If the vault is locked or bw isn't installed, the tools fall back to local keys — a working local setup is never affected.

Available tools:

Category	Tools
Instance ops	list_instances, check_status, get_server_info, run_command, get_logs, transfer_file
AWS observability & security	cloudwatch_list_log_groups, cloudwatch_get_log_events, cloudwatch_top_ips, cloudtrail_lookup_events, ip_ban_list_configs, ip_ban_list_banned, ip_ban_set
Server memory	get_server_memory, list_server_memories, build_server_memory, refresh_server_memory
Session / backend	whoami, api_request
Relay	relay_status, relay_reconnect, mcp_tool_call
Hetzner Cloud	hetzner_list_servers, hetzner_list_server_types, hetzner_list_ssh_keys, hetzner_create_ssh_key, hetzner_delete_ssh_key, hetzner_create_server, hetzner_delete_server, hetzner_power_on, hetzner_power_off, hetzner_shutdown, hetzner_reboot
OVHcloud	ovh_list_ips, ovh_firewall_rules, ovh_ssh_keys, ovh_snapshots, ovh_dns_records, ovh_billing, ovh_invoices, ovh_create_instance, ovh_delete_instance, ovh_start_instance, ovh_stop_instance, ovh_reboot_instance
AWS EC2	aws_list_regions, aws_list_amis, aws_list_instance_types, aws_list_key_pairs, aws_list_subnets, aws_list_security_groups, aws_start_instance, aws_stop_instance, aws_reboot_instance, aws_terminate_instance, aws_run_instances
S3 / Object Storage	s3_list_buckets, s3_list_objects, s3_download_object, s3_create_bucket, s3_delete_bucket, s3_upload_object, s3_delete_object, s3_copy_object, s3_move_object, s3_generate_presigned_url