servonaut

# Servonaut

<!-- mcp-name: dev.servonaut/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.

![Servonaut demo](docs/screenshots/demo.gif)

## Quick Install

**Linux / macOS:**

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

**Windows (PowerShell):**

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

**Or install directly via pipx / pip:**

```bash
pipx install servonaut
```

**Manual install from source:**

```bash
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.

<details>
<summary><b>Copy-paste setup prompt</b></summary>

```
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`, `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.
```

</details>

## Screenshots

<details>
<summary><b>📸 More screenshots</b> — CloudWatch Top IPs, IP banning, AI chat, sidebar, instance list</summary>

![Instance List](docs/screenshots/instances.png)
*Instance list — AWS, Hetzner, OVH, and custom servers merged into one view*

![Sidebar with full feature set](docs/screenshots/instances-sidebar.png)
*Sidebar reveals Fleet Memory, Memory Sync, Secrets, Settings, and per-provider management for OVH and Hetzner*

![AI Chat Assistant](docs/screenshots/instances-chat.png)
*Built-in AI assistant with MCP server integration — chat with local providers or hosted Servonaut AI*

![CloudWatch Logs Browser](docs/screenshots/cloudwatch.png)
*CloudWatch log browsing with Top IPs analysis, geolocation, and abuse scoring*

![IP Ban Manager](docs/screenshots/ip-ban-manager.png)
*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](docs/demo-mode.md) for what is redacted and how to use it.

</details>

## Features

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

### Core & connectivity

- **Interactive TUI** — mouse + keyboard, powered by [Textual](https://textual.textualize.io/).
- **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](docs/hetzner.md)

### 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](docs/proactive-monitoring.md)
- **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 input** — dictate into the chat panel with `ctrl+t`. Transcribed entirely on your machine, so audio never leaves the workstation. Two engines: a batch one, or a streaming one that shows words as you speak. Opt-in — nothing is downloaded until you enable it in Settings. → [docs](docs/voice-input.md)

### 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](docs/memory.md)
- **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](docs/db-credential-vault.md)

### 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-server-for-ai-agents)
- **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 crede