Installation

Install Servonaut on Linux, macOS, or Windows. One install gives you all three ways to use it: the interactive terminal UI for day-to-day server management, scriptable CLI commands for automation and CI, and a built-in MCP server for AI agents.

System requirements

Method 1: pipx (recommended)

pipx installs Servonaut into an isolated Python environment — no dependency conflicts, and upgrades are simple.

Prefer plain pip? pip install servonaut works too, but installs into your active Python environment instead of an isolated one — pipx is the safer default. You can also install from source: git clone https://github.com/zb-ss/servonaut.git && cd servonaut && pipx install .

Method 2: Linux / macOS auto-installer

A shell script that installs Python (via pyenv if needed), creates a virtual environment, and installs Servonaut. Suitable for fresh servers and CI environments.

The script will:

1. Detect your OS and package manager (apt, brew, yum, pacman).
2. Install Python 3.10+ if not already available.
3. Install pipx and Servonaut.
4. Add servonaut to your PATH.

Method 3: Windows (PowerShell)

Verifying the installation

First run: launch the app

Run plain servonaut (no arguments) to launch the Servonaut app in your terminal — the primary way to use Servonaut. It opens to a unified instance list that merges AWS EC2 (all regions), OVHcloud, Hetzner Cloud, and your custom servers into one searchable table, with a sidebar for SSH keys, logs and security tools, fleet memory, settings, and your account. Full mouse and keyboard support; press ? anytime for the keybinding reference and Q to quit.

Sign in

Signing in to your Servonaut Cloud account (Free, Solo, or Teams) unlocks the cloud features (hosted AI, memory sync, config sync, teams).

In the Servonaut app: Account / Login, then Login with servonaut.dev

Or in a terminal:

Either way, the device flow gives you a URL and short code you approve from any browser on any device, so it works on headless boxes too. Sign in once per machine — the session is shared by the Servonaut app, every CLI subcommand, and the MCP server, and stored at ~/.servonaut/auth.json. To sign out, choose Logout on the same Account / Login screen, or run servonaut logout; both revoke the session and remove the local tokens.

If you want your hosted AI chats, including the ones you start on the web, to run tool calls on this machine, keep the Servonaut app open (it connects automatically) or keep the relay listener running with servonaut connect. Want to record a screencast safely? servonaut --demo replaces IPs, account IDs, hostnames, and secrets with deterministic fakes on every screen. Next step: the Quick Start walks you through your first SSH session, log tail, and remote command.

Optional dependencies

Servonaut's core TUI works without extra packages. Install these to unlock additional features:

AI log analysis needs no extra install — it works out of the box. After installing a provider SDK, run servonaut --setup-ovh for guided OVHcloud credential setup; Hetzner needs a Read & Write API token (from your config, $HCLOUD_TOKEN, or ~/.config/hcloud/token).

Agent-only / headless install

No TUI required — Servonaut can be installed purely as an MCP backend for a coding agent. servonaut --mcp runs fully headless and never loads the terminal UI, so this works on servers and CI boxes. Install with the mcp extra and wire up your agent in one step:

Servonaut is also listed in the official MCP Registry as dev.servonaut/servonaut, so MCP-aware clients and registry aggregators can discover and install it directly. The registry launch command is uvx --from 'servonaut[mcp]' servonaut --mcp.

Configuration is identical to a full install: ~/.servonaut/config.json, the same guard levels, and the same audit trail at ~/.servonaut/mcp_audit.jsonl. To connect a Servonaut Cloud account without the TUI, run servonaut login (headless OAuth device flow — approve in any browser on any device; --no-browser skips opening one locally). See the MCP Server docs for details.

Upgrading

Servonaut checks for new releases at startup and shows an update action in the TUI's main menu when one is available (press U). From the command line, either of these works:

Uninstalling

To remove Servonaut, uninstall the pipx package. You can also delete the config directory at ~/.servonaut/ if you no longer need your configuration — it holds your settings (config.json), auth tokens, logs, and the MCP audit trail (mcp_audit.jsonl).

If you registered the MCP server into a coding agent with servonaut --mcp-install, also remove the Servonaut entry from that agent's MCP configuration — otherwise the agent keeps pointing at a binary that no longer exists. Consider signing out before uninstalling (Logout on the app's Account / Login screen, or servonaut logout) to revoke the machine's session server-side.

Troubleshooting

servonaut: command not found

Your PATH doesn't include the pipx bin directory. Run:

Python version too old

Check your Python version with python3 --version. If it is below 3.10, upgrade:

AWS instances not showing up

Servonaut uses your default AWS CLI credentials. Ensure the AWS CLI is configured and your IAM role has ec2:DescribeInstances permission. Verify with aws ec2 describe-instances. Inside the TUI, press R on the instance list to force a refresh from AWS (the list is cached and refreshed in the background otherwise).

SSH key permission denied

SSH private keys must have permissions 600. Fix with chmod 600 ~/.ssh/your_key. The TUI's SSH Keys screen shows your agent status and supports key auto-discovery from ~/.ssh plus per-instance key mappings.