Warp-style command blocks and a multi-step AI agent, without the bulk. Local models run in-process with Metal on Mac, or Vulkan with automatic CPU fallback on Windows. No Ollama and no daemon to babysit. Cloud models sit behind the same interface.
Published 11 Sept 2026 114 downloads across all releases
Why VTerminal
Modern AI terminals tend to be Electron apps that phone home for every completion. VTerminal is a native Tauri app that treats your shell, your machine and your consent as the things that must not be replaced.
Instead of a reimplemented shell
A real zsh -il shell on macOS or Bash in the
default WSL2 distribution on Windows, each over its native
PTY. vim, htop, tmux and ssh run in the real shell,
not a reimplementation.
Instead of cloud round trips
The default model is a 9B GGUF running inside the app process via llama.cpp, with Metal on Mac or Vulkan and automatic CPU fallback on Windows. Nothing leaves the machine unless you pick a cloud model. There is no daemon to maintain.
Instead of an agent with free rein
In a session you are driving, every command a model writes passes an approval gate. A scheduled action runs only what you armed it for in advance, and skips and records everything else. Natural-language suggestions are inserted into your prompt, never executed. Restored tabs never reconnect on their own.
The Terminal
Shell integration marks every command as a block, so the app knows what you ran, where, and how it ended. That is also exactly the context the model needs.
portable-pty runs zsh -il on macOS or
Bash in the default WSL2 distribution on Windows, rendered by
xterm.js 6 with a WebGL renderer. Full TUI support, and saved SSH
hosts with one-click connect.
Exit-code badges, copy the command or just its output, re-run, or attach a block to the AI as context. Positions come from live terminal markers, so they never drift.
The reader thread blocks above a watermark and the UI
acknowledges every 256 KB, so cat-ing a
gigabyte file won't balloon memory.
Tabs, in-terminal search, persistent command history, and a command palette for actions and model switching. Use Command on macOS or Ctrl+Shift on Windows.
Nested sessions are detected by command shape. While you're on a remote host, local paths and git branch are withheld from the model rather than quietly misreported.
Veviad Developer UI (default), Veviad UI, Midnight, Nord, Solarized Dark and Light, each with a matched terminal ANSI palette, not just recoloured chrome.
The AI
The same Provider trait covers in-process llama.cpp,
Anthropic, OpenAI, Mistral and any OpenAI-compatible server you
run yourself. Every feature below works the same whichever you
pick.
Describe the goal, or type # at an empty prompt, then
and get a command inserted into your prompt, ready to read before
you press enter.
One click on a failed block streams a diagnosis of what went wrong, plus a corrected command you can inspect and run.
A chat panel with your blocks, their output and your files as context. Resizable, and it keeps its proportion when you resize the window.
Multi-step runs that propose commands, execute them in your visible terminal, and read the real output before deciding what to do next.
off → low → medium → high → max, per model, showing
only the rungs a model actually accepts because a wrong value
is a 400, not a downgrade.
Drag, paste or pick. An optional on-device vision sidecar transcribes screenshots, so even a non-vision chat model can work with them.
Conventions to keep, tools to prefer, the language to answer in. Three fields — all AI, Agent only, Chat and Ask — added to the built-in instructions rather than replacing them. They tune how the model works; they cannot grant a permission or approve a command.
A saved sequence of commands and prompts, run on a schedule against a local shell or a saved SSH host. Experimental and off by default. It fires only while VTerminal is open — no tray icon, no launch agent, no background process — and every step is recorded, including what it wanted to do and was not allowed to.
A conversation with no terminal attached, kept in its own
threads with their own history, model and MCP servers. It can
search Knowledge, but it has no run_command: the
terminal stays Agent-only.
Pair a local tab with a live ssh tab and drive both
from one conversation. Each target keeps its own approval mode,
and the run stops if either tab drifts from the machine it was
bound to.
Model Context Protocol
Connect several remote or local MCP servers, choose them per chat, and expose only the tools that conversation needs. MCP tools work in Ask, Agent and the Chat workspace, while terminal commands remain Agent-only. See the MCP setup and security guide.
Select multiple servers for a conversation. Defaults apply to new chats, while every chat can keep its own server and tool choices.
Connect HTTPS endpoints using JSON or request-scoped SSE. VTerminal negotiates protocol versions and supports compatible legacy initialization lifecycles.
Run npx, uvx, Docker, or an exact
command on macOS and Windows through WSL2. Local MCP stays off
unless the mandatory sandbox self-test passes.
OAuth 2.1 with PKCE, bearer tokens, and custom secret headers are built in. Credentials remain in the operating-system vault, and exported configuration is redacted.
Tool discovery is paginated and cached. Each server is a compact group in the chat picker, where individual tools can be enabled or disabled for that conversation.
Calls show the server, exact tool, and complete arguments. Allow once, deny, or remember that exact tool until its server configuration or schema changes.
Knowledge
Attach local SQLite buckets and permission-filtered Qdrant collections to the same Ask or Agent request. VTerminal creates the right query embedding for every bucket, searches each source independently, and fuses ranked results without comparing incompatible raw scores.
Download, verify, load and test a pinned model from Settings → Knowledge, with progress, cancellation, RAM and disk estimates, and license acceptance where required. No Python, conversion, compilation or arbitrary model files.
Multilingual E5 Base and Large remain unavailable until signed, checksum-pinned Veviad Q8 GGUFs pass multilingual parity tests against the official Sentence Transformers models.
Add a Qdrant database REST URL (normally port 6333) and granular database key. VTerminal uses REST only, lists managed collections that key may see, and keeps attachment read-only unless the credential allows document or collection management.
Managed buckets require Qdrant 1.16+. Their immutable
metadata.vterminal contract stores the exact profile,
vector and payload schema in Qdrant itself. Unmarked collections
stay hidden instead of asking every client to recreate a fragile
local field mapping. Local bindings from before the managed
contract remain under Advanced as read-only search sources. Qdrant stores extracted chunks, metadata and vectors, not
original binaries.
Profiles fingerprint the model, revision, dimensions and exact
query/document transforms; changing one creates a new profile
and requires re-embedding.
Pick files or folders, preview estimated chunks and cloud transfer, then follow persistent Extract → Chunk → Embed → Upload progress, even while the document list is collapsed. Jobs are queued immediately, run automatically, resume safely after interruption, and failed jobs can be retried without selecting the source again or duplicating documents.
Chat, vision and embedding models have separate jobs: chat writes answers, vision transcribes attached images, and embeddings map documents and queries into a retrieval vector space.
The signed standalone vterminal-docs CLI installs
from the UI into ~/.local/bin on macOS. The Windows
installer places it in VTerminal's managed user bin directory,
and Settings reports or repairs that copy. It shares profiles,
model cache, connections, chunking
and job records with the app for repeatable terminal automation.
TurboQuant is advanced and off by default. VTerminal confirms the saved configuration from Qdrant before updating the UI. It keeps the original vectors, so it can be disabled; bits2, bits1.5 and bits1 are advanced choices that trade recall for lower memory use and a different search-speed profile. The CLI handles text, structured text, page JSON and text-layer PDFs; OCR-required files are directed to the UI.
Experimental · Disabled by Default
Reusable Runbooks turn a versioned YAML checklist into a visible
check → apply → verify workflow. Use one to assess a
server baseline, remediate it with approval, or install software
without losing the operator decisions and output behind the
result.
Import a local package rooted at runbook.vrun.yaml.
Each run snapshots the original YAML, canonical JSON and both
digests, so editing a package cannot rewrite live or historical
execution.
Native steps run in the terminal you can see, including an SSH or container session you opened yourself. Every shell action requires a fresh approval and target attestation; agent permission modes never carry over.
Completed, exceptional, failed and cancelled runs produce a
canonical report.json. Human-readable
report.md is derived from it, with approvals,
deviations, comments and captured evidence. Where a step kept a
full artifact, you can open it from the report.
A step can declare what must be true and the exact conditions that prove it. The model picks commands for the distribution it actually finds; the engine runs those conditions and decides. Per-step bounds cap commands, time and rounds, and can refuse network access or privilege escalation. Read how goal-directed steps work.
ansible.playbook runs through a user-installed
ansible-runner with digest-bound approval and structured
per-host outcomes. Check and verify stay preview-only, and apply
still requires verification.
Safety
This matters more in a terminal than anywhere else, so it is worth being precise about what is enforced and what is not.
Every proposed command is checked for whether it is read-only and whether it reaches the network independently, since a fetch that writes no file still pulls unreviewed content into a loop that proposes shell commands. Both are shown when a card is required.
For a session you are driving, the permission mode is per session, never persisted, and never inherited by a new tab. Reads and Smart retain approval gates, Auto runs standard commands but protects sensitive operations, and Full runs every executable command without approval. Deny rules and disabled capabilities still block execution.
A scheduled action is the one exception, and it is bounded. Full is not offered to it at all. The arming is tied to that action's target, steps and attachments, and editing any of them resets it. Attaching a knowledge bucket or an MCP server caps it at reads. Anything the mode does not cover is skipped and recorded, never left waiting.
For an agent run you start, approved commands run in the tab
you're looking at, not a hidden subprocess. You see exactly what
ran, and it runs wherever that tab is, including over
ssh.
A scheduled action runs in the background by default, where there is no tab to watch — so every step is recorded instead: the command, its exit code and a capped extract of its output. Driving a real terminal tab is a separate opt-in.
With web access off, the model's fetch tooling is never sent in the first place, and network-shaped commands are refused before an approval card is even drawn.
A command you rewrite before approving is treated as your own text on your own gesture, not as model output. It is deliberately not re-classified.
Restored sessions never replay anything. An ssh tab
you had open offers Reconnect; it does not reconnect
itself. A scheduled action set to catch up on a missed
occurrence runs at most once, and only after the app has
settled — never as part of starting up.
The command classifier cannot see through a script the agent
wrote in an earlier step, an alias in your dotfiles, a
base64-decoded one-liner, or python -c. It is
documented as best-effort in the app itself and should not be
relied on as a security boundary. What actually enforces "no
internet" for a capable model is the withheld tool, not the
string match.
Models
Chat models write and reason, the optional vision sidecar transcribes images, and embedding models power Knowledge retrieval. Each has a curated catalog and a separate runtime role rather than one model being treated as interchangeable with another.
GGUF weights running inside the app via llama.cpp with Metal on macOS or Vulkan with automatic CPU fallback on Windows. Downloads are resumable and range-checked, with live progress, speed, ETA, cancel and retry directly on each chat or vision model card. Multi-Token Prediction accelerates compatible models automatically, verifies every draft with the target, and safely falls back to standard decoding. Gains vary by model, prompt, context and hardware.
Qwen3.5 9B is the default, sized to run on a 32 GB M1 Pro.
Frontier models behind the same trait, with per-model effort mapping onto each vendor's own parameter.
Provider keys, Hugging Face tokens and remote-server tokens stay
in macOS Keychain or Windows Credential Manager (service com.veviad.terminal).
They never round-trip to the UI or settings.json.
Point VTerminal at any OpenAI-compatible server, press Test, and pick which of the served models to expose.
<think> traces split out
Hosts are only contacted behind an explicit Test and are never probed in the background. A token-bearing connection requires HTTPS, except for localhost or loopback HTTP.
A second local model loaded beside the chat model, purely to transcribe the images you attach.
Transcribed text is fenced and labelled as data. A screenshot is attacker-controllable by construction.
Switching models is one keystroke from the ⌘K / Ctrl+Shift+K palette, and every reply keeps the name of the model that wrote it.
Download
The macOS build is signed and notarized. Windows 11 is available as an unsigned preview for WSL2 and Bash. Both installers include on-device inference with automatic hardware acceleration.
Stable
Apple Silicon · macOS 13 Ventura or newer
Developer ID signed, notarized, and stapled for normal Gatekeeper verification.
Download SHA256SUMS.txt next to the disk image, then run:
shasum -a 256 -c SHA256SUMS.txt
Preview
x64 · WSL2 default distribution · Bash
Preview status: the installer is not Authenticode signed. Windows may show an unknown publisher. Verify its checksum before choosing More info → Run anyway.
Compare the installer with SHA256SUMS.txt, then follow the Windows guide if WSL2 is not ready.
Get-FileHash .\VTerminal_0.6.5_x64-setup.exe -Algorithm SHA256
Keyboard
Open Source
Issues and pull requests are welcome. Please open an issue before starting substantial work so the approach can be agreed first. If you intend to contribute regularly, get in touch: a licensing agreement may be needed to keep future relicensing possible.