How to Use VTerminal: The Beginner's Guide

CodexFuse Team · 2026-11-03T17:36:16.824Z · 14 min read min read

How to Use VTerminal: The Beginner's Guide

Learning how to use VTerminal starts with one idea: most AI terminals phone home for every completion, and this one does not. VTerminal is a lean, native AI terminal that runs its default model on your own machine — a 9-billion-parameter model loaded in-process, with nothing leaving the computer unless you deliberately choose a cloud model. This beginner's guide walks you through installing it on macOS or Windows 11, your first Suggest, the Agent mode approval gates, the local-versus-cloud model decision, and the scheduled actions that can run your routines.

If you are still choosing a terminal, our Ghostty beginner guide covers the fast minimalist terminal many developers pair with their daily work, and the Claude Code beginner guide covers the coding agent you may already run in a terminal. VTerminal sits between those two worlds: a real shell first, with the AI built into the window rather than bolted onto it.

One disambiguation before anything else, said once: "VTerminal" here means the veviad app (vterminal.veviad.com). It is not Vizrt's "AI Terminal" for broadcast graphics, not the Linux virtual terminal you reach with Ctrl+Alt+F1, not the coding-hui/ai-terminal project, and not a VS Code terminal extension. And a traction note, also said once: the vendor reported 322 downloads across all releases when version 0.6.19 published on 2 November 2026 — this is a very early project, so verify every install channel below at write time rather than assuming a mature ecosystem.

What Is VTerminal, Exactly?

VTerminal is a native AI terminal — Tauri 2 plus Rust, not Electron — for macOS (Apple Silicon) and Windows 11 (x64 preview), whose defining position is that your shell, your machine, and your consent are not replaced. The default model is a 9B GGUF running inside the app process via llama.cpp: Metal on Mac, Vulkan with automatic CPU fallback on Windows. The vendor's homepage states it plainly — "Nothing leaves the machine unless you pick a cloud model. There is no Ollama and no daemon to babysit."

The two visible ideas carry over from the Warp-style terminal generation. First, command blocks: every command you run becomes a block with an exit-code badge, and you can copy the command or just its output, re-run it, or attach a block to the AI as context. Block positions come from live terminal markers, so they never drift away from the output they describe. Second, a multi-step AI agent that proposes commands, executes them in your visible terminal, and reads the real output before deciding what to do next. Underneath both sits a real shell — zsh -il on macOS, Bash in the default WSL2 distribution on Windows, each over its native PTY — so vim, htop, tmux, and ssh run in the real shell, not a reimplementation.

VTerminal is free and open-source under GPL-3.0; the homepage's additional details list the price as 0 EUR, and no paid tier or paid feature appears anywhere on the vendor site. The source lives at github.com/Veviad/VTerminal, where issues and pull requests are welcome.

What Do You Need Before Installing?

The requirements split cleanly by platform, and the Windows side needs prep work. On macOS you need Apple Silicon and macOS 13 Ventura or newer — that combination is the one the vendor calls stable. On Windows 11 you get an x64 preview: it is explicitly testing, "not yet considered stable," and it requires Windows 11 x64 with a WSL2 default distribution running Bash. PowerShell, cmd, distro selection, Windows 10, ARM64, MSI packages, and the Microsoft Store are all unsupported in the preview.

Before installing on Windows, confirm WSL2 is actually ready, because VTerminal will not do admin-level WSL installs for you. In PowerShell, run wsl.exe --status and wsl.exe --list --verbose to confirm your default distribution is version 2, then probe the shell it needs: wsl.exe --exec /bin/bash --noprofile --norc -c "/usr/bin/printf 'Bash is ready\n'". The vendor's Windows guide lists what that default distro must provide: /bin/bash, sh, true, env, setsid, printf, base64, tr, grep, ps, awk, sort, and sleep. If any of that is missing, fix your WSL2 setup first — the installer cannot.

How Do You Install VTerminal?

How to install VTerminal on macOS or Windows 11: download the release asset for your platform, verify its checksum, install it, and confirm the shell it expects is present. The vendor publishes both installers from the GitHub releases page; there is no standalone install page beyond the homepage's "installers and requirements" section and the Windows guide.

1. macOS — download the disk image. Grab VTerminal_0.6.19_aarch64.dmg (23.1 MB). Open it, drag VTerminal to Applications, and open it normally from Applications. The build is Developer ID signed, notarized, and stapled for Gatekeeper, so macOS should not complain.
2. macOS — verify the checksum. Download SHA256SUMS.txt from the same release and run shasum -a 256 -c SHA256SUMS.txt. Do this before first launch, not after.
3. Windows — verify the checksum first. Download VTerminal_0.6.19_x64-setup.exe (28.7 MB) and check it with Get-FileHash .\VTerminal_0.6.19_x64-setup.exe -Algorithm SHA256 against SHA256SUMS.txt. This step is mandatory on Windows, because the installer is not Authenticode signed — Windows will show "unknown publisher," and you should only click through More info → Run anyway after the hash matches.
4. Windows — run the per-user installer. Confirm WSL2 and Bash are ready (the checks above), then run the installer. It installs per-user, and uninstalling later via Settings → Apps → Installed apps removes only VTerminal's own managed CLI PATH entry.
5. Turn on update checks if you want them. Settings → Updates: automatic checks are off by default; enabling them checks immediately and then every 24 hours, but installing an update still needs your approval.

What Does Your First Session Look Like?

Your first session has a rhythm: suggest, inspect, run. Suggest (⌘I on Mac, Ctrl+Shift+I on Windows) is the starting move — describe your goal, or type # at an empty prompt and press the key. The crucial design choice: the suggested command is inserted into your prompt, never executed. You read it, edit it if needed, and press Enter yourself. That habit — the AI proposes, you dispose — is the whole philosophy of the app in one interaction.

When a command fails, click the block for Explain & Fix: it streams a diagnosis plus a corrected command you can inspect and run. Ask (⌘J / Ctrl+Shift+J) opens a chat panel with your blocks, outputs, and files as context; it keeps its proportion when you resize the window. Tabs, in-terminal search, persistent history, and the command palette (⌘K / Ctrl+Shift+K, which also switches models) round out the first-session toolkit.

The Chat workspace is worth knowing about early: a conversation with no terminal attached, kept in its own threads with their own history, model, and MCP servers. It can search your Knowledge, but it has no run_command — the terminal stays Agent-only. If you want a scratchpad for thinking without the risk of execution, that is where it lives.

Should You Use the Local Model or a Cloud Model?

Stay on the local model unless you have a specific reason to leave it. The default is the 9B GGUF running in-process — the vendor sizes it to run on a 32 GB M1 Pro — and the local catalog also includes Qwen3.5 2B (ultrafast, for laptops with 8 GB RAM and up), Qwen3.5 4B and 9B, Qwen3.6 27B, and Gemma 4 E2B, E4B, and 31B, with automatic MTP acceleration where compatible. On this setting, nothing you type leaves the machine.

Cloud models are bring-your-own-key: Claude Haiku 5.5, Sonnet 5.5, and Opus 5.5; GPT-6 Luna, GPT-6.1 Terra, GPT-6.1 Sol, and GPT-6 Astra; Mistral Small 4, Medium 3.5, and Large 4 Preview. Your keys stay in the macOS Keychain or the Windows Credential Manager (service com.veviad.terminal) — they never round-trip to the UI or settings.json. A third lane exists for the self-hosted: point VTerminal at any OpenAI-compatible server (Ollama, LM Studio, a llama.cpp server, vLLM, or LiteLLM), press Test, and pick models. If you go that route, our Ollama beginner guide covers running local models the standalone way first.

Two extras sit on the local side: an optional on-device vision sidecar (PaddleOCR-VL 1.6 or Qwen3-VL 4B/8B) that transcribes images you attach, and one-click local embeddings from Settings → Knowledge (Qwen3-Embedding 0.6B Q8 is the recommended starter). Per-model reasoning effort runs off → low → medium → high → max, and the model name is shown on every reply so you always know what answered.

How Does Agent Mode Keep You in Control?

Agent Mode is a multi-step loop — propose, execute in your visible terminal, read the real output, decide the next step — with one non-negotiable rule: nothing runs without you. Every model-written command passes an approval gate in a session you drive, and a command you edit before approving counts as your own text, not the model's.

Approval modes are set per session and are never persisted or inherited: Reads (look, don't touch), Smart (the default gates), Auto (fewer prompts), and Full (the model drives). Start on Smart and only loosen the mode for sessions where you genuinely understand the blast radius. MCP tools follow the same philosophy: every MCP call asks for approval unless you "always allow" that exact tool for that exact server and schema, and the approval auto-expires if the config or schema changes.

What Are Scheduled Actions and Standing Instructions?

Scheduled actions are saved sequences of commands and prompts that run on a schedule against a local shell or a saved SSH host — think a morning status digest or a nightly backup check. They are experimental and off by default, and the design is deliberately conservative: a scheduled action fires only while VTerminal is open — no tray icon, no launch agent, no background process. Every step is recorded, including what the action wanted to do and was not allowed to. "Full" mode is never offered to scheduled actions, arming is tied to the specific target, steps, and attachments (editing any of them resets it), and a missed occurrence catches up at most once, only after the app has settled — never during startup. Do not treat this as a cron replacement; it is a convenience for routines you would run while sitting at the terminal anyway.

Standing instructions are the quieter feature: three fields — all AI, Agent only, and Chat and Ask — where you record conventions to keep, tools to prefer, and the language to answer in. They are added to the built-in instructions rather than replacing them, they tune how the model works, and they cannot grant a permission or approve a command. If you find yourself repeating "always use pnpm" or "answer in short sentences," this is where that goes.

Can VTerminal Drive Your SSH Servers Too?

Yes, and it treats remote machines with visible caution. Save SSH hosts and connect with one click; restored ssh tabs offer a Reconnect button but never reconnect on their own. The headline feature is Local and Remote Together: pair a local tab with a live ssh tab and drive both from one conversation — for example, building locally while tailing logs on the server. Each target keeps its own approval mode, and the run stops if either tab drifts from the machine it was bound to.

Nested sessions get special handling: when the agent detects it is working on a remote host, local paths and the local git branch are withheld from the model rather than misreported. That is a small detail with an outsized effect — it stops the classic failure where an AI confidently runs a local path on a remote box.

VTerminal vs Warp vs a Plain Terminal

Where does VTerminal actually sit? This comparison uses the vendor's own published facts for VTerminal's column:

The honest read: VTerminal is the pick when you want Warp-style blocks and an agent but refuse to send your terminal sessions to someone else's cloud — and you are on one of its two supported platforms. Warp wins on platform breadth and maturity; the plain terminal wins on zero moving parts. VTerminal's bet is that "stays on your machine" is a feature, not a limitation.

5 Beginner Mistakes to Avoid

Sources

1. VTerminal homepage — vterminal.veviad.com (version 0.6.19, published 2 Nov 2026; platform coverage; install channels; license GPL-3.0; price 0 EUR; 322 downloads; Tauri 2 + Rust; 9B GGUF in-process via llama.cpp; Suggest, Ask, Agent mode, scheduled actions, standing instructions, Chat workspace, SSH pairing)
2. Veviad/VTerminal GitHub releases — v0.6.19 release notes (Full-mode SSH approval fixes, New Chat race fixes)
3. Veviad/VTerminal docs/MCP.md — MCP server setup, sandboxing, approval rules
4. Veviad/VTerminal docs/WINDOWS.md — Windows 11 x64 preview requirements, WSL2 prep, per-user installer behavior

Frequently Asked Questions

Is VTerminal really free?

Yes. It is open-source under GPL-3.0 and the vendor lists the price as 0 EUR, with no paid tier or paid feature anywhere on the site. The only money involved is yours to a model provider: if you connect a cloud model, you bring your own API key and that provider bills you.

Does VTerminal work on Linux or Intel Macs?

No. The supported platforms are macOS on Apple Silicon (macOS 13 Ventura or newer, the stable combination) and Windows 11 x64 (a testing preview, not yet considered stable). Linux, Windows 10, ARM64 Windows, and Intel Macs are all unsupported.

Do I need Ollama or a local model server for the on-device model?

No. The default 9B model runs in-process via llama.cpp — Metal on Mac, Vulkan with automatic CPU fallback on Windows. There is no Ollama to install and no daemon to babysit; the "stays on your machine" design is the point.

Can the AI run commands without my approval?

No. Every model-written command passes an approval gate in a session you drive, and approval modes (Reads, Smart, Auto, Full) are set per session and never persisted or inherited. A command you edit before approving counts as your own text. MCP tool calls ask for approval the same way.

Is VTerminal the same as Vizrt's AI Terminal?

No — different product entirely. Vizrt's "AI Terminal" configures broadcast-graphics AI features; veviad's VTerminal is a developer terminal with Warp-style command blocks and an on-device AI agent. The Linux virtual terminal (Ctrl+Alt+F1) is a third, unrelated thing.