AI assistant

Voktty's AI subsystem is BYOK. It can call cloud providers with your key or connect to a local model without sending project data to a Voktty service.

Providers

The provider registry includes:

  • OpenAI
  • Anthropic
  • Google
  • xAI
  • Cerebras
  • Groq
  • DeepSeek
  • Mistral
  • OpenRouter
  • OpenAI-compatible custom endpoints
  • LM Studio, MLX and Ollama for local inference

Model metadata includes context limits, capabilities, reasoning behavior and pricing where the provider exposes stable information. The default model is selected by the registry and can be changed in Settings.

Configure a provider

  1. Open Settings > AI.
  2. Select a provider and model.
  3. Add the API key when the provider needs one.
  4. Set a custom base URL only for a compatible endpoint or local provider.
  5. Send a small read-only request to verify the connection.

Keys go through the secrets_* Rust commands and are never stored in the settings file or localStorage. Network requests go through the Rust proxy, which applies SSRF and DNS-rebinding protections.

Agent workflow

The agent builds a model request from the active session, project memory, optional persona and live workspace context. It streams text and tool calls through Vercel AI SDK v6 semantics and stops after a bounded number of steps.

The live context bridge is lazy. When a tool needs it, Voktty resolves the active terminal working directory and up to the last 300 lines of terminal context. It does not snapshot every terminal on every turn.

Tools and approvals

Read-only tools can inspect authorized files and directories after passing the secret-path deny-list. Mutating tools require an in-app approval:

Category Examples Approval
Read Read file, list directory, search, glob Automatic after security checks
Edit Write, edit, multi-edit, create directory Required
Terminal Run a command, run a shell session Required
Background Spawn or inspect background processes Required
Delegation Run a named sub-agent Controlled by the tool surface

The deny-list applies to both reads and writes. Paths such as .env, SSH keys, credential stores and keychain data must not be bypassed by a prompt or tool argument.

Edit review

AI edits open in an ai-diff tab. Review hunks individually and accept or reject them. Only accepted edits reach the write tool. In plan mode, edits can be queued and reviewed as a batch before execution.

Sessions and composer

Conversations are organized into named sessions and persisted through the Tauri store. The composer supports text, image attachments, text files, terminal or editor selections and voice input. Selections are attached as structured context rather than pasted into the text area.

Prompt snippets use #handle. File attachments use @path from the workspace. These are composer features, not a separate extension or skills system.

Sub-agents and custom agents

Built-in sub-agents provide focused exploration, code review, security and general analysis with reduced tool subsets. Custom agents can define their own system prompt and allowed tools. A sub-agent cannot recursively invoke itself through the same delegation tool.

Voice input

Voice input can use browser speech recognition or configured transcription providers such as OpenAI, Groq and whisper.cpp. The default provider is browser speech recognition when available.

Safe usage checklist

  • Review the workspace root before asking for edits.
  • Treat shell commands and background processes as consequential.
  • Prefer a read-only question before a mutation.
  • Review every diff hunk before accepting it.
  • Never paste API keys or credentials into prompts.
  • Use a local provider when project data must stay on the machine.