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.
No AWS account? That's fine. Wire up OVH Cloud or Hetzner Cloud via the in-TUI setup wizards, or add raw SSH hosts via the next step.
Step 3 — Connect a cloud provider or add custom hosts
Servonaut treats AWS, OVH Cloud, Hetzner Cloud, and arbitrary SSH hosts as first-class — they all show up in the same searchable instance list.
Each cloud provider has a guided setup; arbitrary hosts go in custom_servers.
Settings → OVH Setup
→ Full guide
hcloud token file by default.
Settings → Hetzner Setup
→ Full guide
~/.servonaut/config.json
The rest of this section walks through adding raw SSH hosts. Cloud-provider wizards are documented on their dedicated pages.
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 |
username | No | SSH username (defaults to root) |
ssh_key | No | Path to SSH private key |
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.
The instance list shows the active bindings in the footer. The most common shortcuts:
| Key | Action | Notes |
|---|---|---|
| Enter / O | Open actions menu | Full action overlay for the selected server |
| S | SSH into server | Opens an SSH session in your terminal |
| C | Run command | Execute a one-off command over SSH |
| T | SCP file transfer | Upload or download files via the SCP overlay |
| B | Browse files | Remote file browser for the selected server |
| L | View logs | Opens the log viewer for the selected server |
| A | AI analysis | Analyze the selected server's context with your AI provider |
| M | Server memory | Open the encrypted memory snapshot for the selected server |
| K | Manage SSH key reference | Attach or change the SSH key Servonaut uses for the server |
| V | Verify SSH | Probe the SSH connection without opening a shell |
| Y | Copy row | Copy the selected server's row to the clipboard |
| R | Refresh | Reload the instance list from every configured provider |
| / | Search / filter | Filter servers by name, tag, or keyword |
Other screens (log viewer, CloudTrail explorer, memory viewer) have their own bindings — open any screen and check the footer or press ? for the overlay.
Step 5 — Enable AI
Servonaut has two AI paths:
- Servonaut AI (Solo & Teams) — a hosted gateway with its own dollar budget. No personal API key needed; just
servonaut loginand start chatting from the F2 panel. - Bring your own key — Anthropic, OpenAI, Gemini, or Ollama (local install or Ollama Cloud). Each provider's key sits under its own
ai_provider.<name>_api_keykey, so they coexist and you can switch from the chat-panel header.
Anthropic (Claude)
Servonaut uses the provider's current default model. To pin a specific model, add anthropic_model with the model ID of your choice — see the Configuration reference.
OpenAI
Set openai_model to pin a specific model; otherwise the provider default is used.
Google Gemini
Ollama (local) or Ollama Cloud
Local Ollama needs no key. For Ollama Cloud, set ollama_api_key and point base_url at https://ollama.com/api.
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.
Solo and Teams plans include access to the hosted Servonaut AI gateway. After servonaut login, hit F2 to open the chat panel — no provider keys required. The plan's monthly dollar budget is shown inline; run servonaut ai quota to print it from the CLI.
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.
--mcp-install accepts claude, opencode, cursor, windsurf, vscode, or all.
After registration, the client can use Servonaut tools such as
list_instances, run_command, and get_logs.
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 mcp