Vehla Docs.

Getting started

Vehla is a native macOS menu-bar command center. It combines app launching, file search, clipboard intelligence, window management, notes, drawing, Kanban, dictation, selection tools, local AI, BYOK cloud AI, MCP, and installable command extensions in one keyboard-driven palette.

Install

Download the DMG from vehla.app/download. Open it, drag Vehla.app into Applications, eject the DMG, and launch Vehla. Version 8.5 is build 406 and requires macOS 15.0 or later on Apple Silicon. Vehla lives in the menu bar; click the aurora glyph or press your palette hotkey to begin.

The public DMG is delivered from https://vehla.s3.us-east-2.amazonaws.com/Vehla.dmg and is verified with SHA-256 before updater installs: 330b9c2a0c553cfd51bb4bd41f2219495a1e526c8d9761317f82cb85cbe67ebc.

Permissions

Vehla asks only when a feature needs macOS access. You can revoke any permission in System Settings → Privacy & Security.

• Accessibility. Required for selected-text capture, Magic Rewrite replacement, QuickGlass positioning, window management, Folder Dock placement, Shelf drag behavior, and Flow text injection.
• Input Monitoring. Required for global hotkeys, SnapWheel mouse triggers, Flow push-to-talk, Folder Peek, and system-wide text expansion.
• Screen Recording. Required for Snipe Text, screenshot capture, and screen-region vision actions.
• Microphone and Speech. Required for Flow dictation and Voice Notes transcription.
• Calendar, Contacts, Reminders, Automation, and Notifications. Requested only when you use agenda, contact, reminder, Messages, music, notification, or extension features that need them.

Onboarding

First launch introduces appearance, hotkeys, permissions, Flow setup, Read Aloud providers, local AI models, and optional Quick Surfaces. You can re-run it from Settings → General → Run onboarding again. The onboarding flow adds Dock Widget previews plus everyday behavior, AI, palette, and search preferences.

Your first action

1. Select text in any app.
2. Press Option Space, or your custom palette hotkey.
3. Type a few letters of an action, such as rewrite, summarize, translate spanish, ask, or clip.
4. Press Return. Results stream in Markdown with copy and paste controls.

What's new in 8.5

Vehla 8.5 keeps Island readable over light apps and across desktops, makes SnapWheel modifier shortcuts recover from interrupted keyboard monitoring, and enables text expansion for free users.

• QuickGlass. A configurable action bar appears when you select text, with copy, Read Aloud, Magic Rewrite, translation, summary, grammar, explanation, and custom palette actions.
• Magic Rewrite. Rewrite focused text in place with default tones, per-run tone selection, custom tones, and dedicated shortcuts.
• Flow. Hold Fn, speak, and release to transcribe and paste with private speech models.
• Read Aloud. Use on-device Kokoro English voices or multilingual ElevenLabs voices from your own account.
• Clipboard upgrades. Tabs, local image intelligence, multi-select, named stacks, rich URL clips, privacy rules, and AwesomeCopy sync.
• Notch / Island upgrades. Voice Notes, System Activity, Recent Links, top-attached Notch behavior, and per-tab settings.
• Store. Install command extensions with permissions, secrets, updates, catalog search, isolated execution, and signed publisher trust.

The palette

Keyboard shortcuts

Settings lets you bind global shortcuts for Magic Rewrite, Magic Rewrite with Tone, SnapWheel, every AI action, native commands, and all window snap positions.

Search and launch

The palette searches apps, files, native commands, AI actions, snippets, personas, Store commands, Docker apps, workflows, aliases, and custom searches. Extension and plugin commands rank above file and folder results, and popular apps expose curated, non-blocking actions.

Use filters and modes when you know the kind of result you want: :actions for actions, :snip or / for snippets, :persona for personas, #native for native commands, and #ai for AI actions. The footer opens Canvas, Notes, Kanban, Recall / Ask Memory, Scratchpad, MCP, Emoji, Clipboard, Snippets, Personas, Downloads, and Settings.

Native actions

Native actions run without an AI model. Vehla includes app launching, file search, Finder selection actions, web shortcuts, calculator, unit and currency conversion, dictionary lookup, Contacts, Calendar, Reminders, bookmarks, browser history, music controls, timers, Wi-Fi/Bluetooth and volume toggles, lock/sleep/restart, empty Trash, Apple Shortcuts, terminal commands, password and UUID generators, emoji, QR codes, colors, symbols, ports, Homebrew, media downloads, and keep-display-awake.

Clipboard

Type clip, :clip, or clipboard to open Smart Clipboard. Vehla keeps up to 1,000 clips by default, with searchable tabs for text, URLs, images, pinned clips, and all history.

• Text and URL clips. Copy, paste, pin, rename, tag, clean formatting, extract links, copy Markdown links, or ask AI about the clip.
• Image clips. Local analysis extracts OCR text, QR codes, screenshot details, dimensions, and dominant colors.
• Multi-select and stacks. Select multiple clips, join them, reorder them, save named stacks, and paste groups back into the front app.
• Privacy. Use private mode, sensitive-content controls, pinned-clip protection, ignored apps, and per-app retention rules.
• AwesomeCopy. If enabled, AwesomeCopy can replace Vehla's watcher while syncing history into Vehla in the background.

Quick utilities

Use qr for QR codes, color for color values, symbol and sf for SF Symbols and Unicode, math for the scratchpad, speedtest for network speed, port 3000 and kill port 3000 for developer cleanup, emoji fire for emoji search, and commands for the built-in command reference.

Files, apps, and system

File search uses Spotlight plus common-folder fallbacks. File rows can reveal in Finder, copy paths, move items to Trash, and run copy/move operations. Finder selection commands operate on whatever is selected in Finder. System commands include latest screenshot, settings panes, eject volumes, quit or force quit apps, lock, screen saver, display sleep, sleep Mac, restart, empty Trash, window snaps, saved layouts, audio output switching, and keep-display-awake.

Inputs and output

Vehla can use typed input, pasted input, clipboard text, selected text, Finder files, screenshots, clipboard images, dropped images, and front-app context. The context label tells you what will be sent. AI results stream as Markdown with copy, paste, formatted RTF, and plain-text options. QuickGlass can deliver results by replacing the selection, showing a compact result, or opening the full palette.

Themes

Vehla 8.0 applies appearance across the palette, Settings, onboarding, License Gate, and What's New. Built-in themes include Aurora, Light, Midnight, Liquid Glass, Clear Liquid Glass, Translucent Cold, Translucent Warm, Minimal, Obsidian, Graphite, Nordic, Vintage, and Custom. The custom theme editor lets you tune colors and glass treatment from Settings.

AI

AI action catalog

Vehla 8.0 ships with 73 built-in AI actions, plus any custom actions you create. Categories include Ask, Magic Rewrite, 11 rewrite tones, writing, translation, code, terminal, email, social, clipboard, productivity, privacy, utilities, vision, and agent actions. Actions can be hidden, favorited, aliased, attached to SnapWheel, or bound to a global hotkey.

• Rewrite tones. Professional, Regular Joe, Friendly, Concise, Confident, Casual, Executive, Funny, Gen Z, Technical, and Customer Support.
• Writing and productivity. Summarize, shorten, expand, grammar, bullets, Markdown, explain, smart compose, todos, calendar event, meeting notes, webpage summary, decision memo, PR description, release notes, and bug report.
• Developer help. Explain code, refactor, convert language, debug, generate tests, SQL helper, generate shell command, explain shell command, and fix shell error.
• Vision and tools. Describe images, extract text from images, ask about screenshots, research and reply, schedule from selection, draft and paste.

QuickGlass

QuickGlass is a selection-triggered floating action bar. Enable it in Settings → QuickGlass. When you double-click, drag-select, or keyboard-select text, QuickGlass appears above the selection with configurable actions.

• Add Copy, Read Aloud, Magic Rewrite, built-in palette AI actions, and custom actions.
• Choose output behavior: replace the selection, show a compact result, or open the palette.
• Configure ordering, delay, drag-handle repositioning, require-Command behavior, and excluded apps.
• QuickGlass uses native Liquid Glass on macOS 26 and a frosted fallback on earlier supported macOS versions.

Magic Rewrite

Magic Rewrite rewrites focused text and replaces it in place. Use the palette action, a dedicated Magic Rewrite hotkey, a Magic Rewrite with Tone hotkey, or QuickGlass. Choose a default tone, pick a tone per run, or create custom tone prompts in Settings → Magic Rewrite. Accessibility is required so Vehla can safely read and replace text in the front app.

Flow dictation

Flow is private push-to-talk dictation. Enable it in Settings → Flow, grant Microphone, Accessibility, and Input Monitoring, pick a speech model, then hold Fn or your custom Flow hotkey. Release to transcribe and paste into the focused field.

Model options include NVIDIA Parakeet, NVIDIA Nemotron, Apple Speech, Apple Speech Analyzer, and multiple Whisper sizes. Flow includes downloadable model management, configurable storage, language selection, live preview, and unload controls.

Read Aloud

Read Aloud speaks selected text from QuickGlass or supported palette flows. Use private on-device Kokoro voices for English, or add an ElevenLabs API key for multilingual cloud voices. Kokoro models can be downloaded, stored, and unloaded locally.

Recall / Ask Memory

Recall is the customer-facing name for Vehla's local retrieval workspace; the in-app action is still called Ask Memory. Trigger it with recall, ask memory, ask notes, chat notes, or knowledge. Depending on Settings, the local index can include notes, clipboard history, Shelf items, snippets, canvases, Kanban boards, Deep Research reports, and selected folders.

Answers include citations. Citation chips can open the source, reveal it in Finder, copy content, or stage supported files on Shelf. 8.0 improves short-prefix and partial-code matches in notes and clipboard clips. Local models keep inference on your Mac; cloud models send the assembled prompt to the selected provider.

MCP tools

Vehla includes a standalone MCP client in the palette. Add HTTP/SSE or local stdio servers in Settings → MCP Client, store credentials in Keychain, review tools, and choose Allow, Ask, or Deny policies per server and tool.

The .mcp workspace supports agent tasks, live tool progress, one-time approvals, manual invocation, server management, audit history, durable run transcripts, cancellation, reconnect, output limits, and clean shutdown. MCP servers receive the prompt and context you choose to share, so only connect servers you trust.

Vision

Vision actions read images and screenshots: Describe Image, Extract Text from Image, and Ask About This Image. Press Option Shift S to capture a screen region. Local Gemma text models do not process images, so vision routes to a configured vision-capable cloud provider with a visible routing notice.

Agent actions

Agent actions let AI call built-in tools before answering. Vehla ships Research and Reply, Schedule from Selection, and Draft and Paste. Built-in tools include Fetch URL, Web Search through your Brave Search API key, Create Calendar Event through EventKit, and Paste Into Front App. Fact Check is a utility AI action that can use web context; Generate Calendar Event is a productivity action.

Deep Research

If Lekh AI Pro is installed, Vehla adds Deep Research from the palette. Jobs can show progress, recover in the background, be cancelled, reconnect after relaunch, use Lekh research models, and deliver reports and source files back to Shelf. Continue in Lekh can hand selected text, clipboard content, files, screenshots, Shelf items, notes, and personas into Lekh.

Surfaces

Notch / Island

Enable Settings → Notch / Island and choose Island, a floating capsule, or Notch, a top-attached surface. Tabs can be toggled individually. 8.0 tabs include Bucket, Music, Next Up, Clipboard, Quick Ask, Timer, Messages, Voice Notes, System Activity, and Recent Links.

• Bucket. Drop files, images, links, or text and drag them back out or hand off to Shelf.
• Music. Control Spotify or Apple Music with artwork, visualizer, queue, and playback controls.
• Next Up. Calendar events with meeting links for Zoom, Meet, Teams, and Webex.
• Voice Notes. Record even after the surface closes, save audio locally, and transcribe with the selected Flow model.
• System Activity and Recent Links. See CPU, memory, thermal state, and enriched link history without opening another app.

Shelf

Shelf is a drag-and-drop staging area for files, images, links, and text. Enable it in Settings, summon with Control Option B while dragging, jiggle a drag to reveal it, or use the menu-bar command. Shelf supports multiple buckets, image preview, open/reveal/share actions, zipping, moving, saving, and Deep Research delivery.

Folder Dock

Folder Dock is a mini folder strip beside the macOS Dock. Pin folders, open paginated folder grids, drag items out, remove items with Command-drag, and let the panel track Dock size and position. Configure it in Settings → Folder Dock.

Folder Peek

Folder Peek previews Finder folders without leaving Finder. Enable it in Settings → Folder Peek, choose Folder Dock or Finder styling, select a folder in Finder, and press Space to open a quick grid preview. Input Monitoring and Accessibility help Vehla detect the Finder selection and show the preview reliably.

SnapWheel

SnapWheel is a radial action wheel opened with middle-click, a configured hotkey, or from the palette. It includes 15 window snap positions, app actions, AI actions, clipboard actions, colors, symbols, QR, ports, layouts, notes, canvas, Kanban, scratchpad, emoji, purge, and memory shortcuts.

The layout editor supports radial drag reordering, accessible list controls, custom AI/app arcs, Focus-aware color profiles, reduced motion, fast flick selection, submenu behavior, and an optional Command-middle-click bypass so the current app receives its normal middle-click action.

Window management

Vehla moves the focused window using Accessibility. Search for window left, window right, window maximize, thirds, corners, center, next display, or previous display. The Layouts workspace saves and restores multi-app window arrangements and can auto-layout apps when they launch. Drag-to-snap shows edge previews while moving windows.

BarKeep

BarKeep hides menu-bar icons behind a separator and chevron. Command-drag icons to the hidden side, click to expand or collapse, use auto-collapse, and Option-click separators for quick controls. Turn it on from Settings → BarKeep. BarKeep is available on macOS 26 and prior only.

Break reminders

Break Reminders show scheduled wellness prompts. Choose Plane, Focus, or Full Blur styles; configure interval, work hours, workdays, message, reduced motion, and Escape-to-dismiss; preview the reminder from Settings.

Floating bubble

The floating bubble is a draggable orb that opens the palette with a click. Enable it from Settings → General → Floating AI bubble.

Workspaces

Notes

Notes is a Markdown workspace inside the palette with folders, tags, backlinks, wikilinks, image attachments, search, live preview, and Quick Capture to daily notes. Notes can be indexed by Recall / Ask Memory and stored in Application Support or an iCloud Drive folder.

Canvas

Canvas embeds Excalidraw in the palette. Create drawings, organize them into folders, tag, search, rename inline, export PNGs, and store canvases locally or in an iCloud Drive folder. Canvases can be indexed for Recall.

Kanban

Kanban is a full planning workspace with folders, tags, board search, customizable columns, WIP limits, priorities, due dates, labels, checklists, archives, drag-and-drop card movement, draggable columns, Markdown export, storage controls, iCloud folders, and Recall indexing. Open it from the footer or with kanban, board, or a board-name match.

Store and extensions

The Store installs command extensions that appear in palette search. Open Settings → Store to browse the catalog, search, preview commands, install, enable/disable, update, filter by runtime, manage permissions, and configure secrets. Extension commands run in isolated background processes with timeouts, bounded output, structured errors, and crash containment.

Store installs verify HTTPS URLs, archive size limits, SHA-256 checksums, secure extraction paths, manifest identity, immutable versioned packages, arm64 Mach-O architecture for native extensions, and publisher signatures for catalog native packages. Publisher signing uses Ed25519, first-use trust, signing-key fingerprints, key continuity checks, and trust revocation.

Developer SDK

Vehla 8.0 documents public extension development for TypeScript/JavaScript and Swift. The TypeScript and JavaScript SDK supports typed invocations, async handlers, clipboard and selected-text context, secure secrets, private storage, network access, file selection, notifications, brokered actions, declarative forms, and rich native results. The Swift SDK supports typed handlers, forms, rich results, brokered actions, signed arm64 executable extensions, confined atomic storage, Codable preferences, structured secret-redacting logs, and permission-aware HTTP networking.

The vehla-swift developer CLI can validate, build, test, package, and code-sign native extensions. Example extensions include GitHub Workflow, Web Inspector, Webhook Runner, Developer Security Tools, File Toolkit, Notification Lab, Swift Hello, and Swift SDK Lab.

Media downloads

Vehla can download audio, video, playlists, direct files, and formats through yt-dlp and ffmpeg. Use download, download audio URL, download video URL, formats URL, extract playlist URL, or direct file URLs. Settings shows tool health, install buttons, download location, history, and recent failures.

Purge and Uninstall

Type purge or uninstall plus an app name to review app bundles, caches, preferences, containers, logs, saved state, and nested Library files before moving selected items to Trash. Protected locations may ask for macOS authorization.

Customize

Snippets and expansion

Snippets are reusable templates filtered with / or :snip. They can use placeholders such as {selection}, {clipboard}, {app}, {date}, {time}, {uuid}, and {cursor}. Turn on system-wide expansion in Settings → Snippets & Expansion to replace triggers in any app, with secure-field exclusions and clipboard restoration.

Custom actions

Custom AI actions make your own prompt behave like a built-in palette command. Give the action a name, category, and prompt; use context variables; favorite it; bind it to a hotkey; add it to SnapWheel; or give it an alias.

Searches, workflows, aliases

Custom searches open URL templates with {query}, {query%}, or {query+}. Workflows can open URLs, run shell commands, or execute scripts through zsh. Aliases let you rename built-in commands, native shortcuts, custom AI actions, searches, workflows, and Store commands. These customizations sync through iCloud where supported.

Hotkeys

Settings → Hotkeys manages the palette hotkey, Magic Rewrite shortcuts, capture shortcuts, Quick Capture, SnapWheel, Flow, window management defaults, action hotkeys, and native command hotkeys. Vehla can also help you reclaim Command-Space from Spotlight if you want the palette there.

Personas and memory

Personas are style instructions applied to prompts. Memory is a small always-on note injected into prompts as system context. Portable persona packs can be imported/exported, and Recall source settings control which local data is indexed for retrieval.

Vehla Packs

Vehla Packs bundle workflows, aliases, custom searches, custom AI actions, snippets, and personas. Starter packs include Productivity & Email, Writing & Content, Developer Essentials, and Research. Packs do not include API keys, license keys, clipboard history, notes, or canvases.

App Intents

Vehla registers Shortcuts.app intents to open Vehla, activate a persona, continue text in Lekh AI Pro, and set SnapWheel Focus appearance. Use them in Focus automations or personal Shortcuts when you want macOS to trigger Vehla without opening the palette first.

AI providers

Local models

Vehla ships an MLX local inference runtime for Apple Silicon. Download catalog models, import compatible MLX models, choose storage locations, warm-start models, or offload them when idle. Text-only actions run on-device when Local AI is selected and a model is available. Vision and tool-using actions require a compatible cloud provider.

Cloud API keys

API keys are stored in macOS Keychain and sent directly from your Mac to the provider. Supported BYOK providers are OpenAI, Anthropic Claude, Google Gemini, DeepSeek, and OpenRouter. Settings includes model pickers and key testing; the palette footer disables providers that are not configured.

Ollama

Point Vehla at a local Ollama endpoint, usually http://localhost:11434, and choose a pulled model tag such as llama3.2:3b. Keep Ollama running before selecting it in the palette footer.

LM Studio

LM Studio works as a local server provider. Start LM Studio's local server, copy its base URL into Vehla, choose a served model, and select LM Studio from the palette footer. Requests go to your local LM Studio server rather than Vehla infrastructure.

Lekh AI Pro

When Lekh AI Pro is installed, Vehla can discover compatible local models, use Lekh as a local provider, hand off context with Continue in Lekh, run Deep Research, and share portable personas. Lekh routes stay hidden until the companion app advertises the required integration capability.

Privacy mode

Use Local AI to route text-only AI actions to a selected local model. If the model is unavailable, Vehla shows an error instead of silently falling back to cloud. Cloud providers, web search, MCP servers, Store extensions, ElevenLabs, updates, and licensing use the network only when you configure or invoke those features.

Licensing and support

Vehla Free

Vehla Free is free forever and does not require a card. It includes the Command Palette, search, utilities, basic window management, a rolling 50-item clipboard history, up to 5 notes and 3 snippets, catalog local models up to 2B parameters, BYOK cloud providers, and 50 successful combined Ask AI sessions and AI Action runs per local calendar month.

Activation

You can try Premium for 7 days with no card required. Vehla Pro is a one-time $29.99 purchase for two Macs. Paste the license email and key into Settings → Privacy & Pro → License. Deactivate a Mac from the same area to release a slot. Without an active trial or license, Vehla continues on the Free plan.

Updates

Vehla checks an HTTPS manifest, downloads the DMG, verifies SHA-256, records pending What's New notes, and installs on relaunch. The menu-bar icon shows an update indicator when a newer verified build is available.

Troubleshooting

• If the palette cannot read text, re-check Accessibility permission and restart the front app.
• If global shortcuts, Flow, Folder Peek, or SnapWheel do not trigger, re-check Input Monitoring.
• If Snipe Text or screenshots fail, re-check Screen Recording.
• If Flow records silence, check Microphone permission, selected input device, and the chosen speech model download.
• If QuickGlass appears in the wrong app, add the app to exclusions or require Command before showing.
• If cloud AI is unavailable, test the provider key in Settings and choose a configured model from the palette footer.
• If Store commands fail, review extension permissions, secrets, catalog trust, and the extension's diagnostic output.