Getting Started

VoxyAI is a Mac assistant you control by voice or keyboard. It formats your dictation, answers questions, works with code, and takes actions like email and calendar through a policy engine you control.

VoxyAI is free. Every model runs on your Mac or on another Mac you pair with it, so there is no license or API key. The iPhone, iPad, and Android apps are free too.

Quick Start

1. Install VoxyAI and grant its permissions. Installation
2. The welcome tour opens on first launch. Its Pick a brain step chooses your model; change it later in Library → Models. Models and Engines
3. Hold fn + shift and speak naturally. You don't need to dictate punctuation.
4. Release fn to stop. The formatted text is pasted into the app you were using.
5. To type a request instead, press fn + ctrl. Keyboard Shortcuts

Installation

System Requirements

• macOS 26 or later on an Apple silicon Mac

Install

1. Download the installer (.pkg) and open it.
2. Launch VoxyAI. It runs from the menu bar, and the welcome tour opens on first launch (later from Help → Welcome to VoxyAI…).
3. Grant the permissions below when asked.

VoxyAI starts at login by default (Settings → General → Start at Login) and tells you when an update is available.

Required Permissions

• Microphone - To record your voice
• Speech Recognition - To turn speech into text, on your Mac
• Accessibility - To read selected text and paste into the active app

Dictation also needs Siri turned on in System Settings → Apple Intelligence & Siri. If it is off, VoxyAI shows an alert with a link there.

Some features ask for more the first time you use them: Camera to scan a pairing QR code, Screen Recording for screen context, Automation and Calendars for actions, Contacts to show names in messages, and Full Disk Access to read Messages.

For Full Disk Access, VoxyAI opens System Settings and shows a card with its icon to drag into the list.

Keyboard Shortcuts

Press the keys in either order. fn on its own does nothing in VoxyAI. The ⌘ shortcuts work while the VoxyAI window is in front.

fn + option needs Writing Coach turned on (it is by default) in Settings → Writing Coach. Writing Coach →

Voice Commands

Speak normally and VoxyAI formats the text for the app you are in (in a code editor, "write a function that..." pastes code). These phrases do something else:

• "translate this to [language]" - Translates the selected text. Say "translate [text] to [language]" to translate what you dictate.
• "explain this code" - Explains the selected code in a window where you can ask follow-ups
• "improve this code" - Suggests a cleaner version of the selected code (also "refactor", "optimize")
• "create an app that..." / "write a script to..." - Opens the New Project panel and builds it in a project chat (Projects and Create README)
• "create a README" - In a code editor, reads the open project and writes its README
• Questions - Requests that start like a question ("why", "should I") or end with a question mark open the chat instead of pasting
• Actions - With Automation on, requests like sending an email go to the chat, which carries them out. Automation

Gotcha: "explain", "what is", "how does", and "describe" count as explain requests. With nothing selected, VoxyAI explains the text on screen if screen context is on, or asks you to select code.

If your Mac's language isn't English, Settings → General → Speech Language switches recognition between it and English.

Your own trigger phrases run before these built-in ones. Custom Commands

Chat

Ask anything in Chats (⌘2). Press ⌘N for a new chat.

• Model - The chip button in the composer picks the model. Models and Engines
• Attachments - Drag files in, paste an image, or click the paperclip. Up to 5 images, PDFs, or text and code files; long files are cut at 50 KB. Images need a model that can see them.
• Thinking - Reasoning models show Thinking while they work, then Thought for …. Click it to read the thinking.
• Sources - Answers from your Knowledge show a numbered chip per document. Click one to open it (a PDF opens at the cited page); right-click for Retry Without This Document. Personal Knowledge
• Verified - With judging on, a badge under the reply shows the judge's check. LLM as Judge
• Edit a question - Right-click a question you sent and choose Edit.
• Tools - The wrench button in the composer picks the MCP servers this chat can use. MCP Servers
• Search - The sidebar search finds words in chat titles and inside messages.
• Export - ⇧⌘E saves the chat as Markdown and ⌥⇧⌘E as PDF.

Models and Engines

Every model runs on your Mac or on a Mac you pair with it. Nothing goes to a cloud AI provider, and there are no API keys. Choose models in Library → Models.

Engines

The Engines card on the Models page shows a checkmark for each engine that is ready. Otherwise, hover over its mark to see what it needs, such as a downloaded model.

Default model

The Default model handles dictation, chat, and any task without its own model. Its menu lists your models grouped by engine. Until a Mac is paired, the menu ends with Pair a VoxyAI Mac, which opens the pairing sheet.

Judge model

Shown while LLM-as-judge is on. The judge checks the other models' answers, so it can't be the Default model, a task's model, or a paired Mac. LLM as Judge →

Models for tasks

Each task can use its own MLX, Ollama, or Apple Intelligence model, or the Default model:

• Translation - Translating text into another language
• Coding - Explaining, fixing, and improving code, dictating into a code editor, and Create README
• Images - Naming screenshots by what they show
• File Management - Planning the moves and renames for Organize Directory

The best installed model for each task is marked Recommended. The Recommendations tab picks the best model for each job on your Mac and downloads it in one click. If a task's model isn't available (deleted, or Ollama stopped), it shows as not available and the task uses the Default model until it is back.

Usage Dashboard

With usage tracking on (Settings → General), the chart tile in the menu bar panel opens the Usage Dashboard: requests, tokens, latency, and speed by engine and model.

iPhone, iPad, and Android

The mobile apps are free and on-device. iPhone and iPad use Apple Intelligence or a paired VoxyAI Mac. Android uses Gemini Nano where the device has it, Ollama models downloaded to and run on the device, or a paired VoxyAI Mac. Choose the model in the app's Settings → Models.

Apple Intelligence Setup

Apple Intelligence is Apple's on-device model, built into macOS. It is VoxyAI's Default model out of the box, with nothing to download in VoxyAI.

Turning It On

1. Open System Settings → Apple Intelligence & Siri.
2. Check that the language is one Apple Intelligence supports.
3. Turn on Apple Intelligence and wait for its models to finish downloading.

Using with VoxyAI

1. Open Library → Models in VoxyAI.
2. The Engines card shows a checkmark next to Apple Intelligence when it is ready.
3. Choose Apple Intelligence as the Default model, the Judge model, or any task's model.

Troubleshooting

VoxyAI lists Apple Intelligence in its model menus only once it is ready. If the Engines card says "Turned off or not supported":

• Confirm Apple Intelligence is on in System Settings and its download has finished. If the download seems stuck, check your internet connection and restart your Mac.
• Check that your language and region are ones Apple Intelligence supports.
• Quit and reopen VoxyAI after turning it on.

MLX Local AI

VoxyAI has a built-in AI engine based on MLX, Apple's machine learning framework. MLX models run inside VoxyAI itself, with nothing else to install.

Downloading a Model

1. Open Library → Models → Download and select MLX. Only models your Mac has enough memory to run are listed.
2. Pick a model marked Recommended, or use the tags above the list to filter by use, such as Chat, Coding tools, Translation, or Images. Each entry shows its download size and the memory it needs.
3. Click the download button. You can cancel at any time; an interrupted download is cleaned up and never shows as installed.

Downloads range from under 1 GB to about 40 GB (more for the largest models on very high-memory Macs), so check your free disk space.

Add a model from Hugging Face (advanced)

At the bottom of the Download tab's MLX list, paste a Hugging Face repo or link, like mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit, and click Check. Before downloading, VoxyAI confirms the repo has MLX weights, a chat format, an architecture it can run, and enough free disk space.

Gated and private models

Some models are gated (you must accept their license first) or private, and VoxyAI tells you when a model needs access. Accept the license on huggingface.co, create an access token in your Hugging Face account settings, then paste it (it starts with hf_) into the access token field at the bottom of the MLX list and click Save. VoxyAI keeps the token in your Mac's Keychain and sends it only to Hugging Face.

Using MLX Models

• In the chat window, open the model picker and choose a model from the MLX section.
• In Library → Models, choose it as the Default model or for one of the Models for tasks.

MLX or Ollama?

Both are free and you can use them side by side.

Memory Use

VoxyAI keeps one MLX model loaded at a time (two on Macs with more than 16 GB of memory, so a judge model can stay ready). Models are released after a period of inactivity or when your Mac is under memory pressure.

Use Them from Your Other Devices

With LLM Host turned on, your paired devices can chat with the MLX models on your Mac. LLM Host →

Removing a Model

In the Download tab's MLX list, click the trash icon next to an installed model and confirm Remove.

Ollama Setup Guide

Ollama is a free, open-source server for running AI models locally. You don't need to install it yourself: VoxyAI can set it up for you.

Let VoxyAI Set Up Ollama

1. Open Library → Models → Download and select Ollama.
2. Click Set up Ollama. VoxyAI downloads Ollama, starts it, and, if you have no Ollama models yet, downloads the one recommended for your Mac.

VoxyAI keeps its copy of Ollama in its own folder, on its own port, so it never conflicts with an Ollama you install yourself. VoxyAI starts it when needed, restarts it if it crashes, and stops it when you quit VoxyAI.

Already Use Ollama?

If Ollama is already running on your Mac, VoxyAI uses it as is, with the models you already have, and doesn't install a second copy.

Installing Models

The Ollama tab lists only models that fit your Mac's memory, with the best picks marked Recommended. Click the download button next to a model.

For any other model from the Ollama library, open Custom Ollama model (advanced), type its tag (for example mistral:7b), and click Download. Larger models need more memory, so choose a size similar to the ones listed for your Mac. ollama.com/library

Using with VoxyAI

• In Library → Models, pick an Ollama model as the Default model or for one of the Models for tasks. The Engines card shows a green checkmark next to Ollama when it is running and has models.
• In the chat window, choose a model from the Ollama section of the model picker.

Removing a Model

In the Download tab's Ollama list, click the trash icon next to an installed model and confirm Remove.

Troubleshooting

Ollama not running

• In the Download tab, select Ollama and click Set up Ollama to start it again.
• If you run your own Ollama, check that it is running in your menu bar.

Model runs slowly or runs out of memory

• Try a smaller variant (for example 8b instead of 14b).
• Close other memory-intensive apps.

LLM Host

LLM Host lets your paired iPhone, iPad, Android device, or another Mac use the MLX and Ollama models installed on this Mac. Run large models on the Mac with the most memory and use them from a lighter device.

Turning it on

Open VoxyAI Settings → LLM Host and turn on Enable LLM Host. The first time, macOS asks for network access; allow it.

Connection mode

• LAN only: devices on the same Wi-Fi or Ethernet network. No router setup.
• LAN + Tailscale: also reachable from anywhere over your Tailscale network. Recommended for remote use. If Tailscale isn't installed or signed in, the settings show an Install Tailscale button or a sign-in hint.
• LAN + Port forward (advanced): reachable at your public IP. Forward the TCP port shown in settings (11435 by default) from your router to this Mac.

The settings list the addresses paired devices can use for the current mode. You can switch modes anytime; paired devices keep working.

Pairing a device

1. On the host Mac, click Pair a new device in LLM Host settings. A QR code appears; it expires after 60 seconds.
2. iPhone or iPad: open Settings → VoxyAI Mac → Pair a Mac, then scan the QR code, discover the Mac on your network, or paste the pairing JSON.
3. Android: open Settings → VoxyAI Mac → Pair a Mac, then scan the QR code or paste the pairing code.
4. Another Mac: open Library → Models and choose Pair a VoxyAI Mac from the Default model menu. Scan the QR code with that Mac's camera, choose Find on this network, or paste the pairing JSON copied from under the QR code.
5. If you can't scan, click "Can't scan? Show the details to type in" under the QR code and enter the values on the other device.

Once paired, pick any model installed on the host Mac from the paired device.

Sync Chats

Turn on Sync Chats with Paired Devices here, then Sync Chats with This Mac on the iPhone, iPad, Android device, or Mac. Their chats are kept on this Mac and stay the same on every device.

Managing paired devices

Pairings are stored on the host Mac. The Paired devices list shows when each device was last seen. Click Revoke to remove one device, or Revoke all to remove every device; revoked devices lose access immediately and must pair again. A device can also unpair from its own settings.

Privacy and security

• Connections are encrypted (HTTPS), and only paired devices can connect.
• Only a short list of model endpoints is exposed; all other requests are blocked.
• Nothing routes through VoxyAI servers.

Let paired devices wake this Mac

Paired devices can't reach a sleeping Mac unless Wake for network access is on. If it's off, LLM Host settings shows a warning with an Open Battery Settings button.

1. Open System Settings → Battery → Options (Energy on desktop Macs).
2. Set Wake for network access to Always.

Coding tools on this Mac

To let Claude Code and other coding tools on the same Mac use your MLX models, use Coding Tools instead. Coding Tools →

LLM as Judge

LLM as Judge has a second AI model check your primary model's responses for hallucinations and clear errors. When the judge flags a response, you decide whether to use it, try again, or cancel.

Setting It Up

1. Open Library → Models → Judge.
2. Turn on Enable LLM-as-Judge. It needs at least two models: one answers, the other judges.
3. Pick the Judge model. It can't be your Default model, a task's model, or a paired Mac.
4. Under Verify which features?, turn on the features to check: Writing Coach (rewrite), Chat, Directory organizer, and Screenshot rename. All are off by default.

The Verified Badge

Chat replies show Checking… while the judge reviews them, then Verified or Flagged. A flagged result opens the Judge Review window: Use Anyway (with your edits), Try Again, or Cancel.

Writing Coach

Writing Coach rewrites text you have already written. Select text in any app and press fn + option. A panel appears next to your cursor with rewrite styles and a field for your own instruction; VoxyAI replaces the selection with the rewrite.

On Home, type or paste text into the Writing Coach card, then click Coach or press fn + option.

Rewrite Styles

Press Esc to close the panel without rewriting. In Settings → Writing Coach, you can turn the feature off and choose which styles appear under Actions. While it is on, Writing Coach is also a quick action in the menu bar's Everyday set.

Tone

The Tone slider in Settings → Writing Coach sets the tone of text VoxyAI formats from your dictation in email, messages, Slack, notes, and other writing apps. It doesn't apply in code editors or Terminal. The default is Auto.

Custom Commands

A custom command is a trigger phrase linked to an AI prompt. Run it by saying or typing the phrase, or by clicking it in the menu bar's Quick Actions.

Built-in Commands

Select text in any app and say a trigger phrase.

Four more built-in commands match the Writing Coach styles and paste into the app: Make Professional ("make it professional"), Make Concise ("make it concise", "shorten this"), Fix Grammar ("fix grammar", "correct grammar"), and Make Friendly ("make it friendly", "make it warmer"). See Writing Coach.

Creating Your Own Commands

Open Library → Commands, click +, and fill in:

• Name, The display name, e.g. "Translate to Spanish".
• When you say, Comma-separated trigger phrases, e.g. "translate to spanish, spanish translation". A command runs if any phrase appears anywhere in what you say or type, so avoid common words.
• Prompt, The instruction sent to the AI. It can use placeholders (below).
• Action, Paste into app (at the cursor), Show in chat (in the VoxyAI chat window, leaving your document alone), or Copy to clipboard.
• Requires selected text, On by default. The command uses the highlighted text and shows an alert if nothing is selected. Turn it off for commands that use only what you said.
• Target apps, Optional app names, e.g. "Mail, Messages". Leave empty for all apps.
• Enabled, Turn the command off without deleting it.
• Quick Actions, Off, Everyday, Developer, or Both: the menu bar Quick Actions set that shows the command. Every command, built-in or new, starts Off.

Right-click the list to Duplicate, Delete, Import..., or Export... commands. Import skips commands whose name you already have.

Placeholders

• {{selected_text}}, The highlighted text.
• {{dictated_text}}, Everything you said or typed, including the trigger phrase.
• {{app_name}}, The name of the frontmost app, e.g. "Mail".

Example

Prompt Template:

Translate the following text as requested in "{{dictated_text}}":

{{selected_text}}

With the trigger phrase "translate to", select text and say "translate to French". {{dictated_text}} becomes "translate to French" and {{selected_text}} the highlighted text.

Quick Actions

Set a command's Quick Actions choice to put it in the menu bar panel. Quick Actions

Quick Actions

One-click buttons in the menu bar panel. Select text, click the VoxyAI menu bar icon, and click an action.

• Everyday - Translate, Organize Directory, and Writing Coach (while it is on)
• Developer - Create README, Explain Code, and Fix Code

1. Pick Everyday, Developer, or Both with the switcher in the panel or in Settings → General → Quick Actions. Turn off Switcher in menu bar to hide it.
2. To add a command, set its Quick Actions choice in Library → Commands. Built-in commands can be added too. Custom Commands
3. In Edit Quick Actions, drag to reorder or uncheck an action to hide it. Reset Order restores the default order.

Clipboard History

Clipboard History records the text you copy in any app. It is off by default: turn it on in Settings → Clipboard. Then press Cmd+Shift+V to open it, find an item, and press Enter to paste it. Only text is recorded; images and files are not.

Browsing & Search

• Items are listed newest first. Each row shows the app it was copied from and when, for example "Safari, 5 min ago".
• Type to search item text and source app names.
• Filter by All, Text, Code, or URLs. Code is detected from keywords (func, class, def), braces, and multi-line structure; URLs need a scheme such as http, https, ftp, or ssh.
• Hover over an item to pin, copy, or delete it. Pinned items stay at the top.
• Drag an item into another app to drop its text there.
• Clear deletes every item except pinned ones.
• The overlay closes when you click anywhere outside it.

Keyboard Shortcuts

AI Search

Turn on AI Search in the overlay to sort results by relevance. VoxyAI first finds items that contain your search text, then sends the first 200 characters of up to 20 of them to your default model (set on the Models page) to rank. It only reorders matches, so search for a word you know is in the item. If the model is unavailable, you get normal text search.

Settings

Open VoxyAI Settings and choose Clipboard. The page also has a Clipboard History button that opens the overlay.

Privacy

Clipboard items are stored only on your Mac, encrypted with AES-256-GCM using a key kept in your Keychain. AI Search text goes only to your default model, which runs on your Mac or on a VoxyAI Mac you paired.

Screen Context

Lets the AI see what you're looking at. When you dictate, use Type to AI, or rewrite with Writing Coach, VoxyAI reads the text in the frontmost window, on your Mac, and adds it to the request.

1. Turn on Screen Context in Library → Memory.
2. Allow Screen Recording when macOS asks.
3. Under Blocked Apps, choose Block an App… to pick apps it never reads. Password managers are always blocked.

• Say "explain this" with nothing selected to explain what's on screen.
• Not used in chat or for translation.
• With User Memory on, it also helps VoxyAI learn the names and terms you use. User Memory

Screenshot Renamer

Gives every new screenshot a name that says what's in it, like quarterly-sales-chart.png instead of Screenshot 2026-10-21 at 3.14.07 PM.png.

1. Turn on Screenshot Renamer in Settings → General.
2. Take a screenshot as usual. A notification shows the new name.

• Works wherever your screenshots are saved.
• The Images model in Library → Models does the naming. One that can see images looks at the screenshot; others read the text in it.
• Everything stays on your Mac.

Older screenshots

Use the Organize Directory quick action: pick a folder, and VoxyAI suggests where files belong, renames screenshots, and finds duplicates. Review the list, uncheck anything you want to keep as is, and click Apply. Duplicates go to the Trash. Quick Actions

Projects and Create README

A project is a folder on your Mac plus the chats about it. Project chats can list, read, and search the folder's files and create or edit files in it. They can't reach files outside the folder.

Opening a Project

On the Projects page, or in the chat sidebar under Projects:

• Open Folder… - turns an existing folder, such as a code repository, into a project
• New Project… - creates a new, empty project folder

Each project keeps its own list of chats. To remove one, right-click it and choose Remove from VoxyAI; its folder and chats stay on your Mac.

Creating and Editing Files

• Every change, including new files and folders, asks first with a preview. Choose Save or Don't Save, or tick Don't ask again in this chat.
• To save new files and folders without asking, turn on Allow New Files Without Asking in the project's Project Settings… (right-click the project).
• Before a file is changed, its current version is kept as a backup in ~/Library/Application Support/VoxyAI/Project Backups.
• Small projects (up to 25 files that fit in a quarter of the model's context) are read in full. In larger ones, the AI reads files as it needs them.
• Project Settings… also holds the project's own Knowledge. Turn on Include Library Knowledge to search Library → Knowledge too.
• Project chats work with every engine.

Build Something New

Hold fn + shift and say, or press fn + ctrl and type, something like "create an app that tracks my workouts" or "write a python script that renames photos". Instead of pasting text, VoxyAI opens a New Project panel:

1. It asks "What should the app do?" (or the script, website, and so on). Describe it, or keep what you already said.
2. It suggests a folder name that isn't taken. Rename it if you like.
3. Click Create. VoxyAI makes the folder, adds it as a project, and starts building in a project chat.

New projects go in the folder set in Settings → General → Projects → Default folder. If it's set to Ask each time, VoxyAI asks where to put each one.

Create README

Create README reads a code project and writes a README covering what it does, how it works, and how to set it up and run it. Start it from the Create README quick action in the menu bar, or say "create a README" while your code editor is in front.

• It uses the project open in your code editor. If it can't tell which one, it asks you to choose the folder.
• It skips dependencies and build output, then reads manifests, the existing README, entry points, and the most central source files, as much as the model can take.
• It uses the Coding model from Library → Models → Models for tasks.

A panel shows each stage (Scanning the project, Reading the code, Understanding it, Writing the README), then the finished README with Open README and Show in Finder. You can click away while it works; the panel comes back when it's done.

Terminal Commands

In Terminal, iTerm2, Warp, Hyper, Alacritty, kitty, and Ghostty, VoxyAI turns what you say into a shell command. It pastes the command at the prompt without running it, so check it and press Return yourself.

Examples

find . -type f -mtime -7

grep -r "config" --include="*.py" .

Coding Tools

VoxyAI can serve your MLX, Ollama and Apple Intelligence models to coding tools on the same Mac, such as Claude Code, so they run on your Mac instead of a cloud API.

Turn it on

1. In Settings → Coding Tools, turn on Serve local models to developer tools. It runs at http://localhost:11436 unless you change Port.
2. Pick the Main model (Automatic uses your AI Provider model) and, optionally, a smaller Quick tasks model. If no coding model is installed, VoxyAI offers to download the best one your Mac can run.
3. Leave Access key empty unless you need one. When it is empty, any key is accepted.
4. Click Test Connection.

Connect a tool

• OpenAI - The OpenAI card lists the Base URL, key, and each model's id to copy. Copy config gives a ready setup for the OpenAI SDK, Continue, or Zed.
• Claude Code - Click Add to ~/.zshrc, open a new Terminal window, and run claude-local. Your regular claude command is unchanged. Copy as settings.json makes every Claude Code session use your Mac's model.
• Ollama tools - Set the tool's Ollama address to http://localhost:11436. It runs alongside Ollama.

Good to know

• Requests run one at a time. If two tools ask at once, the second waits.
• The first reply in a session is the slowest, because the model reads the whole prompt. Follow-up turns reuse it and start much faster.
• Models under about 7B parameters usually fail at tool use. Coding Tools warns when a request is too long for your model.
• The VS Code extension is in Settings → VS Code Extension, and the default projects folder in Settings → General. VS Code Extension

Local API

VoxyAI serves your MLX, Ollama and Apple Intelligence models through an OpenAI, Anthropic and Ollama compatible API, so your own scripts and apps can use them. Nothing leaves your Mac.

Turn it on

1. In Settings → Coding Tools, turn on Serve local models to developer tools. It runs at http://localhost:11436 unless you change Port.
2. Leave Access key empty unless you need one. When it is empty, any key is accepted.

Endpoints

• OpenAI - POST /v1/chat/completions, GET /v1/models. Base URL: http://localhost:11436/v1
• Anthropic - POST /v1/messages, POST /v1/messages/count_tokens. Base URL: http://localhost:11436
• Ollama - /api/chat, /api/generate, /api/tags, /api/show

For model, use an id from /v1/models: an MLX repo id, an Ollama tag, or apple-intelligence. If you set an Access key, send it as Authorization: Bearer or x-api-key.

Examples

List your models:

curl http://localhost:11436/v1/models

Chat with curl:

curl http://localhost:11436/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit",
    "messages": [{"role": "user", "content": "Write a haiku about the sea"}]
  }'

Python, with the OpenAI SDK and streaming:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11436/v1", api_key="voxyai")
stream = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Explain recursion in one sentence"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Python, with the Anthropic SDK:

from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:11436", api_key="voxyai")
message = client.messages.create(
    model="apple-intelligence",
    max_tokens=512,
    messages=[{"role": "user", "content": "Summarize: ..."}],
)
print(message.content[0].text)

Good to know

• Streaming and tool calls work with MLX and Ollama models. Apple Intelligence does not call tools.
• Text only: images and documents in a request are skipped. There is no embeddings endpoint.
• Requests run one at a time. If two tools ask at once, the second waits.
• The server only accepts connections from apps on this Mac. Other devices and web pages in your browser cannot reach it.
• To point Claude Code, Continue or Zed at it, see Coding Tools

IDE Integration

VoxyAI works in any code editor with nothing to install. For VS Code there is also an optional extension.

Any Editor

VoxyAI recognizes code editors, including Xcode, VS Code, Cursor, Windsurf, Zed, Nova, BBEdit, Sublime Text, Android Studio, and JetBrains IDEs. In them:

• With no selection, what you say becomes code (or a code comment) in the file's language.
• With code selected, what you say is an instruction for that code, like "add error handling" or "convert to async/await". VoxyAI pastes back only the changed code.
• Writing Coach tone settings are not applied to code.

For "explain this code", "improve this code", and "create a README", see Voice Commands. Shell commands are covered in Terminal Commands.

VS Code Extension

The free VoxyAI extension connects to the Mac app and adds diff-previewed edits, a chat panel with code context, lightbulb fixes, git tools, and multi-file edits. VS Code Extension →

VS Code Extension

The free VoxyAI extension for Visual Studio Code uses the models you picked in the VoxyAI app on the same Mac. For what VoxyAI does in any editor without it, see IDE Integration.

Installation

1. Install and open the VoxyAI app (see Installation).
2. In Settings → VS Code Extension, click Open in VS Code, or search for "VoxyAI" in VS Code's Extensions panel.
3. It connects on its own, with no pairing or keys. Enable VS Code extension in Settings → VS Code Extension is on by default.

The VoxyAI status bar item shows the connection and the active AI provider. Click it for Reconnect, Open VoxyAI, and Reset connection. The extension also retries every 30 seconds.

Commands and Shortcuts

Shortcuts work when the editor has focus and can be changed in Keyboard Shortcuts. These commands are also in the editor's right-click menu under VoxyAI, and every command is in the Command Palette under "VoxyAI:".

• Every change opens as a side-by-side diff to accept or reject.
• The chat in the VoxyAI sidebar sends the selection, the whole file, or nothing. Its header switches the Mac app's provider and Ollama or MLX model.
• Also: lightbulb fixes for errors, Generate Commit Message, Summarize Current Diff, Edit Across Files, and your custom commands.

Troubleshooting

• App not running: open VoxyAI (or choose Open VoxyAI from the status bar item).
• Turned off: turn on Enable VS Code extension in Settings → VS Code Extension.
• Rate limited or Not responding: VoxyAI is busy; the extension retries on its own.
• Stuck on "Connecting": run VoxyAI: Reconnect to VoxyAI App, or open the chat panel. If that fails, choose Reset connection from the status bar item. Connection details are in View → Output → VoxyAI.
• Changed Port in Settings → LLM Host? Set the VS Code setting voxyai.port to match (default 11435).

Requires Visual Studio Code 1.95 or later.

User Memory

User Memory learns facts about you, such as your sign-off, greetings, terminology, and tools, and adds them to prompts when VoxyAI writes or formats text for you. It is left out of chat answers and translations. It is off by default.

Library → Memory

• Enable User Memory - When off, nothing is learned or added to prompts.
• Learn from Clipboard - Learns your style from text you copy in email, messaging, and notes apps.
• Screen Context - Gives the AI the text in the frontmost window. Needs Screen Recording permission. Under Blocked Apps, choose Block an App… to pick apps it never reads. Password managers are always blocked.
• Identity - Your casual and formal names, used to sign emails and messages.
• Memories - Search, edit, turn off, or delete what VoxyAI has learned, or Clear All.

Personal Knowledge

Add your own documents and VoxyAI answers from them, with the sources it used.

Adding Documents

1. Open Library → Knowledge and turn on Enable Knowledge.
2. Click Add Files or Folders and pick one or more files or folders. Folders are indexed recursively.

• PDFs (scanned ones too, read with text recognition), Word .docx files, and text, Markdown, code and data files.
• Folders are watched, so new, changed and deleted files are picked up on their own.
• Multilingual Search is an optional 335 MB download that finds documents in over 100 languages.
• Each project can have its own knowledge in Project Settings…. Projects

Sources in Answers

• Answers show a numbered chip for each document they used. Click one to see the passage and open the document; a PDF opens at the cited page.
• Right-click a chip and choose Retry Without This Document to ask again without it.

Chat History Migration

VoxyAI keeps chats encrypted on your Mac, with the key in your login keychain. To move them to a new Mac, you need both.

• Migration Assistant (Recommended) - Transfer your user account and applications to the new Mac. Your chats come along.
• Sync - Pair the new Mac with a host Mac and turn on chat sync. LLM Host
• Export - Right-click a chat in the sidebar and choose Export as Markdown… or Export as PDF… to keep a readable copy.

Manual Migration (Advanced)

Keychain Access cannot export password items, so copy the key with the security command in Terminal. Quit VoxyAI on both Macs first.

1. On the old Mac, print the key. macOS asks for your keychain password.

   security find-generic-password -a ChatHistoryEncryptionKey -w

2. Copy the chat-history.db file and the chat-images folder to the same place on the new Mac:

   ~/Library/Application Support/VoxyAI/

3. On the new Mac, save the key, replacing KEY with the value from step 1. The -U flag replaces a key VoxyAI may already have created there.

   security add-generic-password -U -a ChatHistoryEncryptionKey -w 'KEY'

4. Open VoxyAI. If macOS asks whether VoxyAI may use the keychain item, click Always Allow.

Automations

VoxyAI can brief you on your inbox and meetings, and read or act on your email, messages and calendar when you ask in chat. Find it in Library → Automations.

Automations

• Morning Briefing / End of Day Summary - On weekdays at your time (8:00 and 17:00 by default), a summary of your inbox opens in chat. Turn on Include texts to add your text messages. If your Mac was asleep, it runs once later that day.
• Meeting Prep - A briefing 5 to 30 minutes before each calendar event, from the event and recent email with its attendees.
• Meeting Emails to Calendar - When you check your inbox in chat, VoxyAI offers to add meetings it finds to your calendar and draft a reply.

Turning one on asks once, then sets up what it needs: Automation, the service, permission to read, and Calendar access. Each shows Ready, or what's missing with a Fix button.

Ask in Chat

With Automation on, ask in chat: "check my inbox", "reply to 2 saying I'll be there", "add lunch Friday at noon to my calendar". Your policies decide whether each action runs, waits for you in the approval window, or is blocked. Policies

• In the approval window, edit the details, then click Approve or Reject. After 5 minutes it's rejected.
• Nothing runs on its own except briefings and Meeting Prep.
• To stop everything, turn off Enable Automation in Settings → Automation.

Policies

Policies decide what VoxyAI may do in Mail, Messages, Calendar and MCP tools. Find them in Library → Automations → Policies.

• Auto, Confirm, Block - Auto runs the action, Confirm asks you first, Block stops it.
• Priority - The lowest number is checked first, and the first policy that matches decides. If none matches, the action is blocked.
• Templates - Confirm Everything, Read Only, or Block Everything.
• Allowed Actions - The actions the policy covers, such as Read, Send or Delete.
• Scope - Email: Contacts and Domains limit who VoxyAI sends to. Messages: Contacts. Calendar: time only. MCP Server: Servers and Tools. All can be limited to a time window or weekdays. Reading is never limited by Contacts or Domains.
• Content Blockers - Patterns, one per line. If one matches, the policy is skipped.

Click + to add a policy and double-click one to edit it. Delete one with its trash button or by right-clicking it. Setup Wizard, at the top of the Automations page, creates a starter set.

Audit Log

Every decision is listed here. On a denied entry, Create Policy… opens a new policy filled in from that request.

MCP Servers

MCP servers give the AI in chat extra tools, such as searching GitHub or reading files. Every tool call goes through your policies.

Adding an MCP Server

1. Turn on Enable Automation in Settings → Automation. MCP doesn't run without it.
2. In Library → Tools, turn on Enable MCP Servers and click Add Server.
3. Local (stdio) runs a command on your Mac: give the full path (run which npx in Terminal to find it) and space-separated arguments. Remote (HTTP) connects to a URL, with an optional Auth Token and headers.

Each server shows its tool count, Connecting, Failed, or Disabled. Hover over Failed to see the error. Use the slider button to edit a server and the trash button to delete it.

Using MCP Tools in Chat

1. In the chat window, click the tools button next to the attach button and check the servers you want. Only checked servers are offered to the AI; with none checked, it cannot see or call any MCP tool. The button is tinted while a server is checked.
2. Ask in plain language, for example "find open issues labeled bug in my repo". The AI picks a tool and its arguments, and your policies decide whether it runs, asks you first, or is blocked.

Allow Paired Devices

This switch in Library → Tools is off by default. When it is on and this Mac is the LLM Host, chats from paired devices can use MCP tools. Policies still apply, and only Auto policies run remotely because Confirm dialogs cannot reach a remote device. See LLM Host.

Enterprise Deployment

Manage VoxyAI on every Mac with MDM. There is nothing to activate and no API keys to distribute, and the configuration is a plain property list you can write by hand.

What You Can Manage

• The VoxyAI Mac engine. Decide whether users can send requests to another Mac they paired. Apple Intelligence, MLX, and Ollama on the user's own Mac are always available.
• Automation. Turn automation on or off, and install mandatory policies on every Mac.
• MCP servers. Turn MCP on or off, allow or block servers by name, and install locked servers.
• Screen context. Turn Screen Context Awareness on or off and block specific apps from screen capture.
• Secret redaction. Replace MCP tool results that contain API keys, passwords, or tokens before the AI sees them.

Deployment Methods

MDM Managed Preferences (Recommended)

Deliver the keys as managed preferences for this preference domain:

com.voxyai.VoxyAI

Any MDM that supports custom settings for macOS works. Paste the keys from the Configuration Reference as plain plist. macOS stores them in /Library/Managed Preferences/com.voxyai.VoxyAI.plist, where users cannot change them.

• Xavier: Add an App Preferences (managed preferences) profile for the domain com.voxyai.VoxyAI and paste the keys.
• Other MDMs: Add a custom settings profile for the domain com.voxyai.VoxyAI and paste the plist, or upload a .mobileconfig made with the helper script below if your MDM asks for one.

Local Config File (Testing)

To try a configuration on one Mac, or for configuration management tools on Macs without MDM, save the same plist at:

~/Library/Application Support/VoxyAI/enterprise-config.plist

Users can edit or delete this file, so use MDM for anything you need to enforce.

How VoxyAI Finds Your Configuration

• VoxyAI reads the configuration each time it starts. After you change it, quit and reopen VoxyAI.
• A Mac is managed when MDM sets at least one VoxyAI key in com.voxyai.VoxyAI. Without that, VoxyAI uses the local file if it contains at least one VoxyAI key.
• If MDM sets any VoxyAI key, the local file is ignored completely. The two are never merged.
• Keys you leave out keep the user's own choice. Keys VoxyAI does not know are ignored and listed in the log.
• Without any configuration, VoxyAI works normally with every feature available and no restrictions.

Minimal Configuration

Every key is optional. This configuration only turns off the VoxyAI Mac engine, so every request stays on the user's own Mac:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AllowRemoteLLMHost</key>
    <false/>
</dict>
</plist>

Optional Helper Script

You can write the plist by hand. The helper script prints a starter plist, checks yours for unknown keys, wrong types, and incomplete entries, and can wrap it in a .mobileconfig for MDMs that want an uploaded profile. It runs on your Mac and sends nothing anywhere. Download generate-enterprise-config.swift

swift generate-enterprise-config.swift --template > voxyai.plist
swift generate-enterprise-config.swift voxyai.plist
swift generate-enterprise-config.swift voxyai.plist \
  --mobileconfig VoxyAI.mobileconfig --org "Acme Corp"

Enterprise Configuration Reference

Every key VoxyAI reads, with examples. All keys are optional and go at the top level of the plist, in MDM custom settings for com.voxyai.VoxyAI or in the local file.

Key Reference

Value Formats

• Booleans can be written as true or false, 1 or 0, or the strings true, false, yes, or no.
• A list of strings can also be one comma-separated string.
• A key with the wrong type is skipped and noted in the log. The other keys still apply.
• An entry in MandatoryPolicies or MandatoryMCPServers that is missing a required field is skipped. The other entries still apply.

Mandatory Policies

Each entry of MandatoryPolicies is a dictionary with these fields. Automation is default-deny: an action with no matching active policy is blocked. See Automation Engine for how policies match.

<key>AutomationEnabled</key>
<true/>
<key>MandatoryPolicies</key>
<array>
    <dict>
        <key>name</key>
        <string>Read work mail during office hours</string>
        <key>provider</key>
        <string>email</string>
        <key>allowedActions</key>
        <array>
            <string>read</string>
        </array>
        <key>approvalMode</key>
        <string>auto</string>
        <key>scopeDomains</key>
        <array>
            <string>acme.com</string>
        </array>
        <key>scopeTimeWindow</key>
        <dict>
            <key>startHour</key>
            <integer>8</integer>
            <key>endHour</key>
            <integer>18</integer>
            <key>weekdaysOnly</key>
            <true/>
        </dict>
    </dict>
    <dict>
        <key>name</key>
        <string>Confirm every email send</string>
        <key>provider</key>
        <string>email</string>
        <key>allowedActions</key>
        <array>
            <string>send</string>
            <string>reply</string>
        </array>
        <key>blockedContentPatterns</key>
        <array>
            <string>CONFIDENTIAL</string>
        </array>
    </dict>
</array>

Mandatory MCP Servers

Each entry of MandatoryMCPServers is a dictionary with these fields.

<key>MCPEnabled</key>
<true/>
<key>MandatoryMCPServers</key>
<array>
    <dict>
        <key>name</key>
        <string>github</string>
        <key>command</key>
        <string>npx</string>
        <key>args</key>
        <array>
            <string>-y</string>
            <string>@modelcontextprotocol/server-github</string>
        </array>
    </dict>
    <dict>
        <key>name</key>
        <string>company-docs</string>
        <key>url</key>
        <string>https://mcp.acme.com/mcp</string>
    </dict>
</array>
<key>MandatoryPolicies</key>
<array>
    <dict>
        <key>name</key>
        <string>GitHub tools need confirmation</string>
        <key>provider</key>
        <string>mcp</string>
        <key>allowedActions</key>
        <array>
            <string>mcpTool</string>
        </array>
        <key>scopeDomains</key>
        <array>
            <string>github</string>
        </array>
    </dict>
</array>

MCP tools are blocked unless a policy allows them, so pair each mandatory server with a mandatory mcp policy.

How Mandatory Entries Behave

• They show a lock icon. Users cannot delete mandatory MCP servers or switch them off.
• Users can switch a mandatory policy off or edit it, but VoxyAI restores your version the next time it starts.
• Each entry is identified by its name (ignoring upper and lower case), so deploying the same name again updates the entry instead of adding a copy. If two entries share a name, the first one wins.
• Take an entry out of the configuration, or remove the whole configuration, and VoxyAI removes it from the Mac at the next launch.
• If a configuration exists but is not a valid plist, VoxyAI leaves the installed entries as they are.

Example Configurations

Full Lockdown

No paired VoxyAI Mac, MCP turned off, and secret redaction on.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AllowRemoteLLMHost</key>
    <false/>
    <key>MCPEnabled</key>
    <false/>
    <key>EnforceSecretScanning</key>
    <true/>
</dict>
</plist>

Screen Context with Blocked Apps

<key>ScreenContextEnabled</key>
<true/>
<key>ScreenContextBlockedApps</key>
<array>
    <string>com.microsoft.Outlook</string>
    <string>com.tinyspeck.slackmacgap</string>
</array>

Allow and Block MCP Servers

Only the github and company-docs servers can start. The block list wins if a name is on both lists.

<key>AllowedMCPServers</key>
<array>
    <string>github</string>
    <string>company-docs</string>
</array>
<key>BlockedMCPServers</key>
<array>
    <string>shell</string>
</array>

Precedence

1. MDM managed preferences for com.voxyai.VoxyAI. If MDM sets any VoxyAI key, the local file is ignored.
2. Otherwise, the local file at ~/Library/Application Support/VoxyAI/enterprise-config.plist.
3. A managed value replaces the user's own setting each time VoxyAI starts. Keys you leave out keep the user's choice.

Troubleshooting

VoxyAI logs which configuration it used, every skipped key or entry, and keys it does not know. Filter the Console app for the subsystem com.voxyai.VoxyAI and the category Enterprise, or run:

log show --last 10m --predicate 'subsystem == "com.voxyai.VoxyAI" AND category == "Enterprise"'
defaults read "/Library/Managed Preferences/com.voxyai.VoxyAI.plist"
plutil -lint voxyai.plist

Enterprise Security & DLP

Control whether users can send requests to a paired VoxyAI Mac, and redact secrets from MCP tool output.

Engine Control

Engines on the Mac

Apple Intelligence, MLX, and Ollama run on the user's own Mac and are always available, whatever the config says. No data leaves the machine.

AllowRemoteLLMHost

The only engine you can turn off is VoxyAI Mac, which sends requests to another Mac the user paired with LLM Host. When AllowRemoteLLMHost is false, VoxyAI Mac is hidden from every model picker, and if it was the user's default model, VoxyAI switches to Apple Intelligence when it starts. When the key is true or absent, users can pair and use another Mac.

Example: keep every request on the user's own Mac.

<key>AllowRemoteLLMHost</key>
<false/>

Data Loss Prevention (Secrets Scanning)

When EnforceSecretScanning is true, VoxyAI scans the output of every MCP tool call before the AI sees it. If the output contains a detected secret, VoxyAI replaces the whole result with a notice that your organization's secret scanning policy blocked it. When the key is false or absent, tool output is passed through unchanged.

<key>EnforceSecretScanning</key>
<true/>

Built-in Patterns

The scanner looks for these kinds of secrets:

Security Notes

• The configuration is not secret. Managed preferences and the local file can be read by every user and app on the Mac. Do not put credentials in authToken, env, or headers that you cannot afford to expose, and give MCP servers tokens limited to what they need.
• Deploy through MDM for anything you need to enforce. Users cannot change managed preferences, but they can edit or delete the local file.
• AutomationEnabled, MCPEnabled, and ScreenContextEnabled are applied each time VoxyAI starts. They are not locked in the app, so a user can change them until the next launch.
• Apple Intelligence, MLX, and Ollama run on the user's Mac. The only VoxyAI engine that sends requests elsewhere is VoxyAI Mac, which AllowRemoteLLMHost turns off. MCP servers you allow can reach whatever they are built to reach, so use AllowedMCPServers to limit them.
• Check the Enterprise log category after each change to confirm VoxyAI read what you deployed.