Quick Start

Get Servonaut installed and managing your first server in under 5 minutes. The TUI is the whole interface — install, run servonaut, and you're managing servers. Headless automation has its own CLI path, and AI agents get the MCP server — both signposted where relevant.

Step 1 — Install Servonaut

Servonaut needs Python 3.10+ and an SSH client (standard on Linux/macOS, OpenSSH on Windows). 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.

Option B: Linux / macOS auto-installer

One-line installer that handles everything including Python and dependency setup.

Option C: Windows (PowerShell)

Requires Windows 10 / Windows Server 2019 or later.

Once installed, Servonaut keeps itself current: servonaut --update upgrades in place, and the TUI shows an update action when a new version is available.

Step 2 — First run

Launch the TUI by running servonaut in your terminal.

On the very first launch, Servonaut will:

1. Create ~/.servonaut/config.json with default settings.
2. Auto-discover AWS EC2 instances if the AWS CLI is configured and credentials are available.
3. Open the interactive TUI showing your server list — one searchable table merging every configured provider, with a collapsible sidebar for everything else (logs & security, tools, account).

The first time you connect to a server, a banner offers to build its server memory — a quick probe that captures OS, disk, web stack, databases, and runtimes so they're at hand on every later visit. Press y to probe or n to dismiss.

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 are added on the Custom Servers screen.

The rest of this section walks through adding raw SSH hosts. Cloud-provider wizards are documented on their dedicated pages.

In the TUI (recommended)

Open Custom Servers from the sidebar (under Core). From there you can add, edit, and remove servers with a guided form — name, host, SSH username, key, and port — including per-server extra SSH options when a host needs special flags. Custom servers get the full treatment: SSH, SCP transfers, the remote file browser, and the log viewer all work exactly as they do for cloud instances.

Headless / scripted: via config.json

Provisioning machines from a script or dotfiles repo? Servers can also be declared directly in ~/.servonaut/config.json under a custom_servers array:

{
  "custom_servers": [
    {
      "name": "prod-web-1",
      "host": "192.168.1.100",
      "username": "deploy",
      "ssh_key": "~/.ssh/id_ed25519",
      "tags": {
        "env": "production",
        "role": "web"
      }
    },
    {
      "name": "staging-db",
      "host": "staging.example.com",
      "username": "ubuntu",
      "ssh_key": "~/.ssh/staging_key",
      "tags": {
        "env": "staging",
        "role": "database"
      }
    }
  ]
}

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 — full mouse support means every action is also a click away.

The instance list shows the active bindings in the footer. The most common shortcuts:

The Server Actions dashboard (Enter or click on any row) is your per-server home: a sectioned action rail (Browse Files, Run Command, SSH Connect, SCP Transfer, Scan Results, Logs, AI Analysis, Ban IP, SSH-key management) next to a detail pane showing an at-a-glance memory snapshot — OS, disk, web stack, databases, runtimes, containers. Press L inside the dashboard to toggle an opt-in live resource monitor (CPU, RAM, load, disk, uptime), polled over SSH only while the pane is open.

Other screens (log viewer, CloudTrail explorer, memory viewer) have their own bindings — open any screen and check the footer or press ? for the overlay. Escape always goes back, Q quits, and dragging with the mouse selects (and auto-copies) text on any screen.

Step 5 — Enable AI

Servonaut has two AI paths:

1. Servonaut AI (Solo & Teams) — a hosted gateway with its own dollar budget. No personal API key needed; just sign in (TUI Account → Login, or servonaut login on headless boxes) and start chatting from the F2 panel.
2. 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_key key, so they coexist and you can switch from the chat-panel header.

Either way, F2 toggles the AI chat panel alongside every screen. The chat can call Servonaut's own tools against your instances, and the active server's memory snapshot is injected as context automatically (with a staleness banner if it's old).

Setting a provider key in the TUI

Open Settings from the sidebar (under Tools). The configuration editor covers AI provider selection and per-provider API keys — pick a provider, paste or reference your key, and you're done. No restart needed.

For headless machines or scripted setups, the same values live in ~/.servonaut/config.json. The snippets below show each provider's minimal config.

Anthropic (Claude)

{
  "ai_provider": {
    "provider": "anthropic",
    "anthropic_api_key": "$ANTHROPIC_API_KEY"
  }
}

Servonaut uses the provider's current default model. To pin a specific model, add model with the model ID of your choice — see the Configuration reference.

OpenAI

{
  "ai_provider": {
    "provider": "openai",
    "openai_api_key": "$OPENAI_API_KEY"
  }
}

Set model to pin a specific model; otherwise the provider default is used.

Google Gemini

{
  "ai_provider": {
    "provider": "gemini",
    "gemini_api_key": "$GEMINI_API_KEY"
  }
}

Ollama (local) or Ollama Cloud

{
  "ai_provider": {
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "ollama_api_key": ""
  }
}

Local Ollama needs no key. For Ollama Cloud, set ollama_api_key and point base_url at https://ollama.com/api.

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. Tools are gated by a three-tier guard system (readonly / standard / dangerous), and every call is audit-logged locally to ~/.servonaut/mcp_audit.jsonl. See the MCP Server documentation for the full tool list and guard-level configuration.

Remote access for hosted agents: servonaut connect

On paid plans, Servonaut AI chats (including conversations started on the web) can dispatch tool calls to your machine over the internet. The TUI starts this relay automatically after you sign in; on headless boxes, run servonaut connect in the foreground or servonaut connect --bg to detach it. servonaut connect --status shows whether your machine and your account agree the link is up. Your tokens never leave your machine — agents send tool requests; execution and auditing happen locally under the same guard rules, and headless approvals are capped by the relay.ai_tool_auto_approve tier in config.json. Paid plans also include a hosted MCP endpoint for plan-gated tools — see the MCP docs.

Automating with the CLI

Everything above used the TUI, but every major feature also has a scriptable, non-interactive command for cron jobs, CI runners, and headless servers:

CLI commands use documented exit codes for scripting (e.g. the ai tree: 0 success, 2 unauthenticated, 4 quota exceeded), and Ctrl+C always exits cleanly with code 130 — never a traceback. See the Configuration reference for environment overrides and per-command details. For a flat listing of every subcommand, flag, and exit code, see the CLI Reference.

What's next