AI assistant

The ai console verb lets an operator configure an LLM connection and ask it questions, optionally grounded in the files under a Context Directory. It is an NGBackup extension built on the AI resource. Supported providers: Anthropic (Claude, the default) and OpenAI.

The verb has these subcommands:

ai show
ai configure ai=NAME [provider=…] [model=…] [endpoint=…] [contextdirectory=…] [confirmdestructive=…] [apikey=…]
ai query ai=NAME <prompt> [output=json]
ai context <list|put|get|delete> ai=NAME …

ai show

Lists the configured AI resources — provider, model, endpoint, Context Directory, and whether an API key is sealed. The key value is never printed.

*ai show
AI resources (1):
  primary
    Provider: anthropic
    Model: claude-opus-4-8
    Endpoint: (default)
    ContextDirectory: /opt/backup/context
    ApiKey: sealed
    ConfirmDestructive: yes

Add output=json for a machine-readable envelope.

ai configure

Sets fields on an existing AI {} resource (add the block to backup-dir.conf first — at minimum AI { Name = primary }). Any combination of provider=, model=, endpoint=, contextdirectory=, confirmdestructive=, and apikey= is accepted; a reload follows so the change is live.

*ai configure ai=primary apikey=sk-ant-...
2000 OK ai resource `primary` configured (1 field(s) set)

The key is sealed, not stored in the config

apikey= seals the key into the Director’s secrets.enc store and rewrites the ApiKey directive to @secret:ai-primary-key. The plaintext key is never written to backup-dir.conf. This requires the Director’s master key (master.key beside the config, or NGBACKUP_MASTER_KEY) — the same key that unseals daemon passwords.

ai query

Sends <prompt> to the model. Every UTF-8 text file under the resource’s Context Directory is concatenated (newest first, capped at ~100 KB total) into the system prompt, so the model can answer from your runbooks, policy notes, or config excerpts.

*ai query ai=primary What retention does the Default pool use, per the context?
(context: 2 file(s))
The Default pool uses a 365-day volume retention ...

Add output=json to receive {ai, model, context_files, response}.

Grounding the model

Drop reference material into the Context Directory (/opt/backup/context by default, auto-created when the Director starts or reloads). Plain-text formats work best — Markdown, .txt, .conf excerpts. Files are included newest-first until the ~100 KB cap is reached; the reply notes how many files were used.

Live catalog grounding (read-only tools)

Beyond static context files, ai query gives the model a set of read-only Director tools it can call to answer from your live system. The model decides when to call them; you never run them by hand. The tools are strictly read-only — there is no run, cancel, delete, or config set tool:

Tool	Reads
catalog_sql	A read-only SELECT against the catalog
status	Director / SD / FD status
list_jobs	Recent jobs from the catalog
joblog	One job’s log
license	Edition, usage vs caps, expiry
dedup_usage	Global Deduplication store usage

The reply envelope reports which tools were used (tools_used), so an operator can audit how the answer was reached.

ai context — manage Context Directory files over the console

ai context lets you read and write the resource’s Context Directory over the console — no shell on the Director host. File names are basename-only (no path traversal). All four actions take ai=NAME and accept output=json.

ai context list   ai=NAME
ai context put    ai=NAME name=<basename> data=<base64>
ai context get    ai=NAME name=<basename>
ai context delete ai=NAME name=<basename>

• list — files in the Context Directory with their byte size and modified time.
• put — write one file; data= is the base64 of the file’s bytes (capped at 1 MiB per file).
• get — return one file’s contents (raw text in text mode; base64 under output=json, which also handles non-UTF-8 files).
• delete — remove one file.

This is how the Web and Desktop consoles let an operator upload a runbook or policy note straight into the grounding set without touching the host.

Errors

All failures return a stock-shaped 1999 ai … line (or an {error} JSON envelope): missing ai=NAME, no such resource, an unconfigured key, or an Anthropic API error (e.g. an invalid key surfaces as 1999 ai query: Anthropic API returned 401 …). No key material appears in any message.