Configuration

How to configure Servonaut — in the app for day-to-day changes, and through ~/.servonaut/config.json for automation, headless machines, and full control.

Changing settings in the app

You rarely need to hand-edit JSON. Most settings on this page have an in-app home, and the TUI writes your changes back to config.json for you:

• Settings (🔧) — scan rules, AI provider selection and per-provider API keys, AbuseIPDB key, OVH credentials, and Memory Sync per-feature settings.
• Custom Servers (💻) — add, edit, and remove non-AWS servers, including per-server extra SSH options.
• SSH Keys (🔑) — set the default SSH key and per-instance key mappings, check SSH agent status, and auto-discover keys from ~/.ssh.
• Account → Login — sign in to servonaut.dev; this is all the setup the hosted Servonaut AI and relay features need.

The reference below documents every key in the file — useful when you provision machines with scripts, manage dotfiles, or run Servonaut on headless boxes where the TUI never opens.

Full example config

{
  "default_key": "~/.ssh/id_ed25519",
  "default_username": "ec2-user",
  "terminal_emulator": "auto",
  "aws": {
    "default_region": "us-east-1"
  },
  "custom_servers": [
    {
      "name": "prod-web-1",
      "host": "192.168.1.100",
      "username": "deploy",
      "ssh_key": "~/.ssh/id_ed25519",
      "port": 22,
      "provider": "Hetzner",
      "tags": {"env": "production", "role": "web"}
    }
  ],
  "ai_provider": {
    "provider": "anthropic",
    "anthropic_api_key": "$ANTHROPIC_API_KEY",
    "openai_api_key": "$OPENAI_API_KEY",
    "gemini_api_key": "$GEMINI_API_KEY",
    "ollama_api_key": "",
    "model": "",
    "base_url": ""
  },
  "ovh": {
    "enabled": true,
    "endpoint": "ovh-eu",
    "application_key": "$OVH_APPLICATION_KEY",
    "application_secret": "$OVH_APPLICATION_SECRET",
    "consumer_key": "$OVH_CONSUMER_KEY",
    "cloud_project_ids": ["$OVH_PROJECT_ID"]
  },
  "hetzner": {
    "enabled": true,
    "api_token": "$HCLOUD_TOKEN",
    "default_image": "ubuntu-22.04",
    "default_server_type": "cx23",
    "default_location": "fsn1",
    "require_ssh_keys_on_create": true
  },
  "mcp": {
    "guard_level": "standard",
    "audit_path": "~/.servonaut/mcp_audit.jsonl",
    "max_output_lines": 500
  },
  "relay": {
    "heartbeat_interval": 30,
    "ai_tool_auto_approve": "standard"
  },
  "log_viewer_default_paths": [
    "/var/log/nginx/access.log",
    "/var/log/nginx/error.log",
    "/var/log/auth.log"
  ]
}

AWS settings

AWS needs no Servonaut-specific credentials — the unified instance list reads your standard AWS CLI configuration (~/.aws/credentials and ~/.aws/config) and scans every region for EC2 instances. Results are cached so the list opens instantly; press R in the instance list to force a refresh from AWS. The aws block tunes that behaviour:

The aws block also accepts advanced keys for S3-compatible object storage (including custom endpoints such as OVH Object Storage) and cross-account role assumption.

{
  "aws": {
    "enabled": true,
    "default_region": "eu-west-1",
    "cache_ttl_seconds": 3600
  }
}

Custom servers

Custom servers let you manage any machine — DigitalOcean, bare metal, on-prem VMs — alongside your cloud instances, with full SSH, SCP, and log-viewer support. The easiest way to add one is the Custom Servers (💻) screen in the TUI, which walks you through every field below, including per-server extra SSH options as a multi-line input. For scripted setups, edit the custom_servers array directly:

SSH defaults

Manage SSH keys in the app from the SSH Keys (🔑) screen: set the default key, map keys to individual instances, check your SSH agent status, and auto-discover keys from ~/.ssh. In the file, Servonaut reads its key and username defaults from top-level fields on the main config (below); connection tuning — keepalives and timeouts — lives in a dedicated ssh block.

Bastion / ProxyJump example

{
  "default_key": "~/.ssh/id_ed25519",
  "connection_profiles": [
    {
      "name": "via-bastion",
      "bastion_host": "bastion.example.com",
      "bastion_user": "ec2-user",
      "ssh_port": 22
    }
  ],
  "connection_rules": [
    {
      "name": "private-subnet-via-bastion",
      "match_conditions": {"name_contains": "private"},
      "profile_name": "via-bastion"
    }
  ]
}

Connection keepalives

Long-running, quiet SSH sessions — an agent or MCP tool that opens a connection and then waits on a slow command, a held-open log tail, a bastion hop through an idle firewall — used to get silently reaped by the network in between. The ssh block sends keepalives on every SSH and SCP connection (including both bastion hops) so those sessions stay up. The settings are emitted as standard OpenSSH options: -o ServerAliveInterval=30 -o ServerAliveCountMax=5 -o TCPKeepAlive=yes -o ConnectTimeout=15. The block is additive — there's no config migration, and an absent block means these defaults.

Per-host extra_ssh_options (on a custom server or a connection profile) still layer on top of these, so you can refine or override the keepalive behaviour for an individual host.

{
  "ssh": {
    "server_alive_interval": 30,
    "server_alive_count_max": 5,
    "tcp_keepalive": true,
    "connect_timeout": 15
  }
}

OVH Cloud settings

Enable OVH integration to merge OVH Public Cloud, VPS, and dedicated servers into the unified instance list, and to unlock the OVH Manage screen (lifecycle toolbar, region-first create wizard) plus the OVH sidebar sections for SSH keys, DNS zones, IPs, block storage, and billing. The recommended setup path is the guided wizard — run servonaut --setup-ovh and it captures credentials for either the classic 3-key flow or an OAuth2 service account. You can also enter credentials on the Settings screen, or set the keys manually:

Full per-screen UX reference lives on the OVH Cloud docs page.

Hetzner Cloud settings

Enable Hetzner Cloud as a first-class provider: discovered servers join the unified instance list, and the Hetzner Manage screen gives you a full-lifecycle toolbar (create, power on/off, shutdown, reboot, delete) plus a project SSH-key registry. The token resolves from hetzner.api_token, then $HCLOUD_TOKEN, then ~/.config/hcloud/token — the same chain used by the official hcloud CLI and the Terraform provider. Run servonaut hetzner test-connection to verify the chain resolves and the API is reachable.

Full per-screen UX reference lives on the Hetzner Cloud docs page.

AI provider settings

Pick and configure your AI provider in the app: the first-run picker offers the choice when you first open the AI chat, the Settings (🔧) screen holds the provider selector and per-provider API keys, and the chat panel header (toggle with F2) lets you switch provider per-session. For scripts, override per invocation with --ai-provider <name> (or the SERVONAUT_AI_PROVIDER environment variable), and run servonaut ai provider reset to clear the saved preference so the first-run picker shows again.

In the file, the ai_provider block holds one shared provider selector plus per-provider API-key slots, so you can keep multiple providers configured at once and switch between them at runtime. Servonaut AI on Solo and Teams plans is the zero-config path — no key needed.

MCP server settings

The mcp block governs what AI agents may do on your fleet when you connect them through Servonaut's MCP server (servonaut --mcp, or one-command install into a coding agent with servonaut --mcp-install claude|cursor|windsurf|opencode|vscode|all). The same guard tiers also bound what the relay listener will auto-approve for hosted AI chats (see Relay settings). Regardless of guard level, a built-in blocklist rejects destructive shell patterns, and every tool call is written to a local audit log you can review at any time.

{
  "mcp": {
    "guard_level": "readonly",
    "audit_path": "~/.servonaut/mcp_audit.jsonl",
    "max_output_lines": 200
  }
}

Relay settings

The relay is what lets Servonaut AI chats — including web-originated conversations and headless servonaut ai chat --tools sessions — and your team-mates run tools on this machine. The listener keeps a secure, outbound-only real-time connection open to your account; tool calls are dispatched over it, executed locally under your guard settings, and the results posted back. Your credentials and SSH keys never leave the machine, and every executed call lands in the same audit log as direct MCP calls.

You don't normally start it by hand: after you sign in (TUI Account → Login), the TUI auto-starts an in-process listener and the sidebar shows ● connected. On headless machines, run servonaut connect in the foreground, or manage it as a background process:

• servonaut connect --bg — detach into the background.
• servonaut connect --status — show local + backend connection status, with a warning if they diverge.
• servonaut connect --reconnect — stop then start the listener to heal a stale connection.
• servonaut connect --stop — stop the background listener.
• servonaut connect --force-bg — take over the connection from a TUI's in-process listener.

The TUI and the background listener coordinate through a lock file so only one of them holds the connection at a time. The relay block tunes the listener:

Syncing config across machines

On Solo and Teams plans, the Sync Config (🔄) screen keeps config.json in step across your machines using encrypted snapshots: Pull Latest, Push New, Restore, Rename, and Delete. Snapshots are encrypted in your client with a passphrase only you know before they are uploaded — the passphrase never leaves your machine, and Servonaut's servers only ever store ciphertext they cannot read. When restoring on a new machine, the dialog asks you to enter your existing passphrase (it isn't creating a new one).

Log viewer paths

Configure the default log paths the log viewer offers when you open it for a server (press L in the viewer to switch between them). These are resolved on the remote host, not locally. The field name is log_viewer_default_paths; the shipped default covers common web-server, database, and system logs.

{
  "log_viewer_default_paths": [
    "/var/log/nginx/access.log",
    "/var/log/nginx/error.log",
    "/var/log/syslog",
    "/var/log/auth.log",
    "/var/log/mysql/error.log"
  ]
}

Related keys let you add custom paths and tune discovery and output limits: log_viewer_custom_paths, log_viewer_scan_directories, log_viewer_scan_max_depth, log_viewer_max_lines, and log_viewer_tail_lines.