Configuration
Full reference for ~/.servonaut/config.json — every option explained with examples.
Config file location
Servonaut creates ~/.servonaut/config.json on first run with sensible defaults.
Edit it with any text editor. Changes take effect the next time you launch the TUI.
Full example config
~/.servonaut/config.json
{
"default_key": "~/.ssh/id_ed25519",
"default_username": "ec2-user",
"terminal_emulator": "auto",
"aws_regions": ["us-east-1", "eu-west-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
},
"log_viewer_default_paths": [
"/var/log/nginx/access.log",
"/var/log/nginx/error.log",
"/var/log/auth.log"
]
}
AWS settings
| Key | Type | Default | Description |
|---|---|---|---|
aws_regions |
array | ["us-east-1"] |
List of AWS regions to scan for EC2 instances. All regions are queried on launch. |
example
{
"aws_regions": ["us-east-1", "us-west-2", "eu-west-1", "ap-southeast-1"]
}
Custom servers
The custom_servers array lets you add any server — DigitalOcean, Hetzner, bare metal, on-prem VMs —
alongside your AWS EC2 instances.
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
name | Yes | string | — | Unique server identifier shown in the TUI server list. |
host | Yes | string | — | Hostname or IP address. |
username | No | string | "root" | SSH username (e.g. ubuntu, ec2-user). |
ssh_key | No | string | "" | Path to SSH private key. Falls back to top-level default_key when empty. |
port | No | integer | 22 | SSH port. |
provider | No | string | "" | Provider label (e.g. "DigitalOcean", "Hetzner"). |
group | No | string | "" | Optional grouping label. |
tags | No | object | {} | Arbitrary key/value pairs for filtering. E.g. {"env":"prod","role":"db"}. |
extra_ssh_options | No | array | [] | Extra -o KEY=VALUE pairs for SSH/SCP. Useful for legacy hosts needing e.g. HostKeyAlgorithms=+ssh-rsa. |
SSH defaults
Servonaut reads its SSH defaults from top-level fields on the main config, not from a nested ssh block.
| Key | Type | Default | Description |
|---|---|---|---|
default_key |
string | "" |
Default SSH private-key path used when a server has no ssh_key set. |
default_username |
string | "ec2-user" |
Fallback SSH username when a server or provider does not define its own. |
terminal_emulator |
string | "auto" |
Terminal emulator used when launching SSH sessions from the TUI. "auto" picks the first installed terminal Servonaut recognises. |
instance_keys |
object | {} |
Per-instance SSH-key overrides. Keys are instance IDs; values are key paths. |
connection_profiles |
array | [] |
Named SSH connection profiles for bastion / ProxyJump setups. Each entry takes name, bastion_host, bastion_user, bastion_key, username, proxy_command, ssh_port, and extra_ssh_options. |
connection_rules |
array | [] |
Rules that apply a connection_profiles entry to matching instances. Each rule takes name, match_conditions, and profile_name. |
Bastion / ProxyJump example
config.json
{
"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"
}
]
}
OVH Cloud settings
Enable OVH integration to merge OVH Public Cloud, VPS, and dedicated servers into the unified instance list. Use the guided wizard to capture credentials, or set the keys manually.
| Key | Type | Default | Description |
|---|---|---|---|
ovh.enabled |
boolean | false |
Toggles OVH discovery and the OVH Manager screen. |
ovh.endpoint |
string | "ovh-eu" |
OVH API endpoint. Common values: ovh-eu, ovh-us, ovh-ca. |
ovh.application_key |
string | "" |
OVH application key (classic 3-key auth). |
ovh.application_secret |
string | "" |
OVH application secret. Supports $ENV_VAR and file: prefixes. |
ovh.consumer_key |
string | "" |
OVH consumer key. Supports $ENV_VAR and file: prefixes. |
ovh.client_id |
string | "" |
OAuth2 service-account client ID (alternative to the 3-key flow). |
ovh.client_secret |
string | "" |
OAuth2 service-account client secret. Supports $ENV_VAR and file: prefixes. |
ovh.cloud_project_ids |
array | [] |
Public Cloud project IDs to include in discovery and account-scoped MCP tools. |
ovh.include_dedicated |
boolean | true |
Fetch OVH dedicated servers. |
ovh.include_vps |
boolean | true |
Fetch OVH VPS instances. |
ovh.include_cloud |
boolean | true |
Fetch OVH Public Cloud instances. |
ovh.default_ssh_key |
string | "" |
Default SSH key path used when SSH-ing into OVH-discovered instances. |
ovh.default_username |
string | "" |
Override default SSH username. Empty means auto-pick by provider type. |
Full per-screen UX reference lives on the OVH Cloud docs page.
Hetzner Cloud settings
Enable Hetzner Cloud as a first-class provider. 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.
| Key | Type | Default | Description |
|---|---|---|---|
hetzner.enabled |
boolean | false |
Toggles Hetzner discovery and the Hetzner Manager screen. |
hetzner.api_token |
string | "" |
Hetzner Cloud API token (Read & Write). Supports $ENV_VAR and file: prefixes; leave empty to fall through to $HCLOUD_TOKEN / the hcloud token file. |
hetzner.default_image |
string | "ubuntu-22.04" |
Default OS image for the create wizard. |
hetzner.default_server_type |
string | "cx23" |
Default server type. Hetzner deprecates types per location — keep this in sync with what's available in your default location. |
hetzner.default_location |
string | "fsn1" |
Default datacentre code. Available: "fsn1", "nbg1", "hel1", "ash", "hil". |
hetzner.default_username |
string | "root" |
SSH username for Hetzner-created instances. Hetzner images ship with root as the only pre-provisioned account. |
hetzner.default_hetzner_ssh_key |
string | "" |
Hetzner-side SSH key name or numeric ID — must already be registered with Hetzner Cloud. NOT a local file path. |
hetzner.default_local_ssh_key |
string | "" |
Local file path used for ssh -i when connecting INTO created servers. Falls back to default_key when empty. |
hetzner.require_ssh_keys_on_create |
boolean | true |
When true, refuses to create a server with no SSH keys. Hetzner would otherwise spawn one with a random root password the CLI can't recover, leaving a billed unreachable box. |
hetzner.cost_alert_threshold |
number | 0.0 |
Optional monthly EUR ceiling. 0.0 disables the alert. |
Full per-screen UX reference lives on the Hetzner Cloud docs page.
AI provider settings
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.
| Key | Type | Default | Description |
|---|---|---|---|
ai_provider.provider |
string | "openai" |
Active provider. One of: "openai", "anthropic", "gemini", "ollama", "servonaut". |
ai_provider.model |
string | "" |
Override the provider's default model. Empty string means "use provider default". See each provider's docs for current model names. |
ai_provider.base_url |
string | "" |
Override the provider's base URL. Empty means "use provider default". Used most often with Ollama (e.g. http://localhost:11434 for local; Ollama Cloud base URL for cloud). |
ai_provider.anthropic_api_key |
string | "" |
Anthropic API key. Supports $ENV_VAR and file:/path/to/key. |
ai_provider.openai_api_key |
string | "" |
OpenAI API key. Supports $ENV_VAR and file: prefixes. |
ai_provider.gemini_api_key |
string | "" |
Google AI Studio API key (used for Gemini models). |
ai_provider.ollama_api_key |
string | "" |
Ollama Cloud API key. Leave empty for a local Ollama install — local instances need no key. |
ai_provider.max_tokens |
integer | 4096 |
Maximum tokens to request per response. |
ai_provider.temperature |
number | 0.3 |
Sampling temperature. |
ai_provider.provider_preference |
string / null | null |
Explicit provider preference set by the user (e.g. via the first-run modal). Falls back to provider when null. |
ai_provider.local_fallback_provider |
string / null | null |
Provider name to fall back to when Servonaut AI is unavailable. null disables automatic fallback (privacy-preserving default). Set to "ollama" for on-device prompts or any other supported provider name. |
Secrets syntax
Never hard-code API keys in config.json. Use environment variable or file references:
"anthropic_api_key": "$ANTHROPIC_API_KEY"
// or from a file:
"anthropic_api_key": "file:~/.secrets/anthropic_key"
Servonaut AI — no key needed on paid plans
Solo and Teams subscribers don't need to set any of the keys above. After servonaut login, the chat panel routes through the hosted gateway at mcp.servonaut.dev, which does its own provider failover under your plan's dollar budget.
MCP server settings
| Key | Type | Default | Description |
|---|---|---|---|
mcp.guard_level |
string | "standard" |
Controls what MCP tools are allowed.
"readonly" — read-only operations only.
"standard" — read + safe writes.
"dangerous" — full access including destructive commands.
|
mcp.command_allowlist |
array | see schema | Shell commands the MCP run_command tool may invoke. Defaults to a curated read-only set (ls, cat, grep, ps, df, du, top, free, uptime, whoami, hostname, uname, date, w, netstat, ss, ip, ifconfig, ping, dig, nslookup, head, tail, wc, sort, find, file, stat). |
mcp.command_blocklist |
array | see schema | Regex patterns rejected even when the guard level would otherwise allow them. Defaults block rm -rf, dd, mkfs, shutdown, reboot, fdisk, parted, halt, fork bombs, and sudo rm. |
mcp.audit_path |
string | "~/.servonaut/mcp_audit.jsonl" |
JSONL audit trail of every MCP tool invocation. |
mcp.max_output_lines |
integer | 500 |
Hard cap on the number of output lines returned to any single MCP call. |
config.json — readonly mode example
{
"mcp": {
"guard_level": "readonly",
"audit_path": "~/.servonaut/mcp_audit.jsonl",
"max_output_lines": 200
}
}
Log viewer paths
Configure the default log paths the log viewer offers when you open it for a server.
These are resolved on the remote host, not locally. The field name is log_viewer_default_paths.
config.json
{
"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"
]
}