Servonaut AI

A hosted AI gateway that lets the CLI, TUI, and dashboard ask questions about your servers — no API keys to manage on your side. Billed against a plain-English dollar budget; no token math.

Using AI in the TUI

The fastest way to use Servonaut AI is the built-in chat panel in the TUI. Press F2 on any screen to toggle it — it runs alongside whatever you're doing, whether that's the instance list, a log viewer, or a per-server dashboard.

• Ask about the server you're on. When an instance is active, its server memory (OS, web stack, databases, runtimes, containers) is injected into the conversation automatically, with a staleness banner if the snapshot is old — so the assistant already knows what it's talking about.
• Tools run with your approval. The assistant can call real tools against your fleet — list instances, tail logs, run commands. In the TUI you approve each tool call interactively before it executes; nothing runs behind your back. Tools your plan doesn't allow simply don't appear in the chat surface.
• Budget at a glance. Your remaining quota and top-up balance are shown inline in the chat panel, so you always know where you stand before asking another question.
• Pick your provider per session. The panel header lets you switch between the hosted Servonaut AI gateway (Solo/Teams) and your own local provider keys (OpenAI, Anthropic, Gemini, Ollama including Ollama Cloud) configured under Settings.

For deeper one-off jobs, the per-instance Server Actions dashboard includes an AI Analysis action that runs AI-powered log analysis for the selected server, with a cost estimate shown up front.

How the budget works

Each request is debited from your monthly budget as soon as the response lands. The dashboard widget shows your remaining dollars in real time, the TUI chat panel shows quota and top-up balance inline, and the CLI surfaces a one-line summary on each chat turn. From a terminal, check at any time with:

servonaut ai quota          # human-readable budget, top-up balance, reset date
servonaut ai quota --json   # same, machine-readable for scripts

Top-ups

Burned through your monthly budget faster than expected? Buy a one-time top-up at any time from the dashboard's AI widget, or straight from the terminal:

servonaut ai topup small    # also: medium, large

The CLI opens a checkout page in your browser and refreshes your balance automatically shortly after the purchase completes. (If you press Ctrl+C during the post-purchase wait, only the courtesy balance refresh is skipped — the purchase itself is unaffected.) Top-ups are consumed after your subscription budget is exhausted; they don't roll into the next month.

High availability & failover

Servonaut AI routes each request through multiple upstream providers. The gateway transparently fails over on errors, timeouts, and rate limits, so a single vendor incident does not interrupt your work. If every upstream is unreachable, the API returns 503 upstream_unavailable so the caller can retry or fall back. (A 503 service_unavailable instead means the AI feature itself is switched off — retrying won't help until it's re-enabled.)

You don't pick or configure providers — that's our job. From your side, the only knobs are your monthly budget, your top-up balance, and whether a tool call is allowed under your plan.

Dashboard widget

The account dashboard hosts the AI widget: remaining budget for the current period, a rolling 7-day spend chart, your most recent conversations, and a one-click top-up button. The widget refreshes automatically — spend made from the CLI or TUI shows up on the web view within seconds.

Automating with the CLI

Everything the TUI chat panel does is also scriptable for CI runners, cron jobs, and headless boxes. Sign in once per machine with servonaut login — it works fully headless, printing a URL and short code you can approve from a browser on any other device — and the session is shared by the CLI, the TUI, and the MCP server.

servonaut ai chat "why is disk filling on web-1?"   # buffered single answer, tools off
servonaut ai chat --stream "summarise today's errors" # SSE token streaming
servonaut ai chat --tools "restart the stuck queue worker" # buffered with tool execution
servonaut ai quota --json                            # remaining budget for scripts
servonaut ai conversations list --json               # paginated history
servonaut ai conversations export <uuid> notes.md    # save a thread locally

Buffered (non-streaming) chat defaults to tools off: a buffered request that needed tool execution would otherwise block until the server's wall-clock cap and return nothing useful. Pass --tools to opt in, or --no-tools to force a read-only invocation anywhere. Buffered mode fails loudly on empty or tool-call-only responses rather than printing a blank line.

The ai command tree uses documented exit codes you can branch on in scripts: 0 success, 1 generic error, 2 unauthenticated, 3 entitlement, 4 quota, 5 budget. Pressing Ctrl+C during any command prints a one-line Cancelled. and exits with code 130 — never a traceback.

Conversations are first-class: servonaut ai conversations supports list (with --limit, --before, and --status active|archived|deleted), show, export (Markdown or JSON), archive, and delete (soft-delete — still listable with --status deleted).

Public API surface

For users who want to wire AI into custom scripts directly, the gateway is also a public API. The same dollar budget applies; the same tier-gating applies to tool calls.

Budget exhaustion surfaces as a 402 at the hard cap, and a tier-gated tool invocation is denied with an explanatory error your script can inspect. Full request/response shapes and error envelopes are documented on the API Reference page.

AI tool execution & tier gating

The AI agent can invoke real tools against your infrastructure — list instances, tail logs, run commands, and so on — but only tools whose guard level your plan and entitlements allow. Free can't run any tool; Solo and Teams run readonly and standard tools; the dangerous tier requires an additional dangerous-AI-tools entitlement on your account.

The dangerous-AI-tools entitlement is granted per account: on Solo, enable the Destructive AI tools opt-in under Account → Settings; on Teams, contact support to enable it for your team. Without the entitlement, dangerous tool calls are denied server-side regardless of any client configuration, and dangerous-tier tools are also hidden from the chat surface entirely. The full per-tool catalog and guard-level reference lives on the MCP page.

Tools in headless chat

Tool calls are executed by your own CLI, never by our backend. In the TUI chat panel you approve each call interactively. Headless — servonaut ai chat --tools (buffered), --stream, and conversations started from the web dashboard — tool calls are dispatched to your running servonaut connect listener (foreground or --bg), which executes them and returns the result to the model, even when no TUI is open. Buffered chat still defaults to tools-off for instant text answers; pass --tools to opt in.

Because no human is present to confirm, approval is policy-driven: relay.ai_tool_auto_approve in ~/.servonaut/config.json sets the maximum guard tier the listener executes without confirmation — "readonly", "standard" (the default), or "dangerous". Dangerous-tier execution requires both the entitlement above and the "dangerous" policy value; a tool above your policy tier is denied instantly with an explanatory result the model relays back to you — no hang, no timeout. Every execution and denial is appended to the local audit log at ~/.servonaut/mcp_audit.jsonl with source="ai_chat".

For AI agents

If you drive Servonaut through a coding agent instead of the TUI or CLI, the same gateway, dollar budget, and guard levels apply. The MCP server (servonaut --mcp) exposes the full tool surface locally over stdio, and its mcp_tool_call bridge reaches the hosted MCP server at mcp.servonaut.dev for plan-gated tools. Setup, the per-tool catalog, and the guard-level reference live on the MCP page.

Privacy & data handling

• Prompts are scrubbed — IPv4/IPv6 addresses, emails, URL hosts, and known cloud-default DNS names are replaced with placeholders before the prompt leaves Servonaut for any upstream provider.
• Conversation history is stored encrypted-at-rest under your user id. You can purge any conversation from the dashboard at any time.
• Provider retention follows each upstream's published policy. If retention guarantees matter to your workload, use the CLI or TUI with your own provider key locally for those workflows.