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. Paid from one AI balance in money — no token maths.

Using AI in the TUI

The fastest way to use Servonaut AI is the built-in chat panel in the Servonaut app. Press F2 (or Ctrl+G) 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. From a terminal, use servonaut ai chat (see Automating with the CLI).

• 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.
• Balance at a glance. Your remaining AI balance is 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 AI balance works

Every hosted AI feature — chat, server scans and memory summaries — is paid from one balance, charged for the work each request actually did. The account dashboard shows what's left, the CLI prints it on demand, and each conversation transcript shows what every reply cost. From a terminal:

servonaut ai quota          # your AI balance, top-up balance and renewal date
servonaut ai quota --json   # the same, machine-readable for scripts

• The allowance renews monthly on your billing date; whatever is left of the previous month's allowance expires then — it does not roll over.
• Top-ups are used after the allowance and last 365 days from purchase.
• Requests stop when the balance is empty — nothing is ever charged beyond what you have, apart from finishing a request already in progress.

Top-ups

Used more than your monthly allowance? Buy a one-time top-up at any time from the AI balance card on your dashboard or Billing page, or straight from the terminal:

servonaut ai topup small    # or: 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.) A top-up is used only after your monthly allowance runs out, and stays valid for 365 days from purchase.

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 AI balance (allowance plus any top-ups) and whether a tool call is allowed under your plan.

On the website

The account dashboard shows your AI balance: what's left to spend, how much of this month's allowance remains, any top-up balance with its expiry, a rough “≈ requests left” based on what your own requests typically cost, and when the allowance renews — with a one-click top-up. The card refreshes on its own, so spend from the CLI or TUI shows up within a minute. Usage breaks down what you spent this month by chat, scans and memory summaries, and every conversation transcript shows what each reply cost.

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 — in the Servonaut app with Account / Login → Login with servonaut.dev, or with servonaut login, which 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 app, the CLI, 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" # stream the answer as it is written
servonaut ai chat --tools "restart the stuck queue worker" # buffered with tool execution
servonaut ai quota --json                            # remaining AI balance 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 error — including an empty AI balance, named on stderr — 2 unauthenticated, 3 plan without hosted AI, 4 invalid arguments. See the CLI reference. 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 AI balance applies; the same tier-gating applies to tool calls.

An empty AI balance surfaces as a 402 with a top-up link, 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 Servonaut on your own machine, never by our backend. In the app's 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 machine's relay listener, which executes them and returns the result to the model. The Servonaut app runs that listener automatically while it's open; when it isn't open, run servonaut connect in a terminal (foreground, or --bg to keep it running in the background). 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, AI balance, 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.