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 TUI

Run plain servonaut to launch the interactive terminal UI — 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.

Signing in with servonaut login unlocks the cloud features (hosted AI, memory sync, config sync, teams). The device flow prints 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 TUI, every CLI subcommand, and the MCP server, and stored at ~/.servonaut/auth.json. servonaut logout revokes the session and removes the local tokens.

If you want hosted AI chats or team-mates to dispatch tool calls to this machine, keep the relay listener running with servonaut connect (the TUI starts it automatically after login). 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 running servonaut logout before uninstalling 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.