Installation
Detailed installation guide for all platforms, with optional dependency setup and troubleshooting.
System requirements
| Dependency | Required | Notes |
|---|---|---|
| Python 3.10+ | Yes | Check with python3 --version |
| SSH client | Yes | OpenSSH (pre-installed on Linux/macOS). Windows: Git for Windows or WSL |
| AWS CLI v2 | No | Required for EC2 auto-discovery and CloudTrail features |
mcp |
No | Required for the built-in MCP server |
Provider SDKs (ovh, hcloud) |
No | Install when you wire up OVH Cloud or Hetzner Cloud |
Method 1: pipx (recommended)
pipx installs Servonaut into an isolated Python environment — no dependency conflicts, and upgrades are simple.
On macOS with Homebrew, you can also install pipx via brew install pipx.
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:
- Detect your OS and package manager (apt, brew, yum, pacman).
- Install Python 3.10+ if not already available.
- Install pipx and Servonaut.
- Add
servonautto yourPATH.
Always review install scripts before running them. Read the install.sh source before executing.
Method 3: Windows (PowerShell)
Windows 10/11 includes OpenSSH by default. If it is missing, enable it via Settings → Optional Features → OpenSSH Client. Using Servonaut under WSL 2 also gives a native Linux experience.
Verifying the installation
Optional dependencies
Servonaut's core TUI works without extra packages. Install these to unlock additional features:
Upgrading
Uninstalling
To remove Servonaut, uninstall the pipx package. You can also delete the config directory at ~/.servonaut/ if you no longer need your configuration.
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.
SSH key permission denied
SSH private keys must have permissions 600. Fix with chmod 600 ~/.ssh/your_key.