Quick Start
Get Servonaut installed and managing your first server in under 5 minutes.
Step 1 — Install Servonaut
Choose the installation method that works best for your system.
Option A: pipx (recommended)
pipx installs Servonaut into its own isolated environment, keeping your system Python clean. This is the recommended method.
Install it with pip install --user pipx then run pipx ensurepath. Or use brew install pipx on macOS.
Option B: Linux / macOS auto-installer
One-line installer that handles everything including Python and dependency setup.
Always review install scripts before piping to bash. Read the install.sh source first if you prefer.
Option C: Windows (PowerShell)
Requires Python 3.10+ and Windows 10 / Windows Server 2019 or later.
Step 2 — First run
Launch the TUI by running servonaut in your terminal.
On the very first launch, Servonaut will:
- Create
~/.servonaut/config.jsonwith default settings. - Auto-discover AWS EC2 instances if the AWS CLI is configured and credentials are available.
- Open the interactive TUI showing your server list.
If you don't have AWS configured, that's fine. You can add custom servers manually in the next step — Servonaut works with any Linux server.
Step 3 — Add custom servers
Servonaut supports any server from any provider — AWS EC2, DigitalOcean, Hetzner, bare metal, VMs, etc. You can add servers through the TUI menu or by editing the config file directly.
Via config.json
Open ~/.servonaut/config.json and add a custom_servers array:
| Field | Required | Description |
|---|---|---|
name | Yes | Display name shown in the TUI |
host | Yes | IP address or hostname |
user | Yes | SSH username |
key_file | No | Path to SSH private key (defaults to ~/.ssh/id_rsa) |
port | No | SSH port (default: 22) |
tags | No | Key/value pairs for filtering and grouping |
Step 4 — Basic operations
Once you have servers listed in the TUI, use these keyboard shortcuts to interact with them. Select a server first with the arrow keys or mouse click.
| Key | Action | Notes |
|---|---|---|
| S | SSH into server | Opens an SSH session in your terminal |
| T | SCP file transfer | Opens the SCP overlay for uploading / downloading files |
| L | View logs | Opens the log viewer for the selected server |
| C | CloudTrail explorer | Browse AWS CloudTrail events (AWS servers only) |
| A | AI analysis | Analyze selected logs with your configured AI provider |
| / | Search / filter | Filter servers by name or tag |
| ? | Help | Show all keyboard shortcuts overlay |
| Q | Quit | Exit Servonaut |
Step 5 — Enable AI analysis
Servonaut can analyze your server logs using OpenAI, Anthropic (Claude), or a local Ollama instance.
Configure your preferred provider in config.json:
Using Anthropic (Claude)
Using OpenAI
Using Ollama (local, free)
API key values support $ENV_VAR to read from environment variables, and
file:/path/to/secret to read from a file.
Never hard-code credentials in config.json.
Step 6 — Set up the MCP server
The MCP (Model Context Protocol) server lets AI agents like Claude Code manage your infrastructure via natural language. Servonaut provides a one-command installer.
After running this command, Claude Code will be able to use Servonaut tools such as
list_instances, run_command, get_logs, and more.
See the MCP Server documentation for the full tool list and guard level configuration.
The MCP server requires the mcp Python package. Install it with: pipx inject servonaut httpx mcp