VoxyAI Documentation

Getting Started

VoxyAI is a voice dictation app for macOS that uses AI to intelligently format your speech. Simply speak naturally and VoxyAI will transform your words into properly formatted text.

Quick Start

Install VoxyAI and grant the required permissions
Configure your preferred AI provider (or use the free on-device options)
Press fn + shift to start recording or fn + ctrl to type
Speak naturally - no need to dictate punctuation
Release the shortcut keys to stop - formatted text is automatically pasted

AI Providers

VoxyAI supports multiple AI providers for text formatting. Choose based on your needs:

Apple Intelligence

Free, on-device processing. Your data never leaves your Mac.

Ollama (Local Models)

Run open-source models locally. Free and private. Supports Llama, Gemma, DeepSeek, and more.

Ollama Setup Guide →

OpenAI

GPT-4o and GPT-4o-mini. Requires API key from openai.com

Anthropic Claude

Claude 3.5 Sonnet and Haiku. Requires API key from anthropic.com

Google Gemini

Gemini Pro and Flash models. Requires API key from Google AI Studio.

Groq

Ultra-fast inference. Free tier available. Requires API key from groq.com

Mistral

European AI leader. Powerful models with great multilingual support. Requires API key from mistral.ai

Perplexity

AI with real-time web search capabilities. Great for current information. Requires API key from perplexity.ai

Enterprise Deployment

Deploy VoxyAI across your organization with pre-configured settings, encrypted API keys, and license activation using MDM or configuration files.

Security Design

Enterprise configurations use industry-standard security:

Ed25519 Signatures - Configurations are cryptographically signed to prevent tampering
AES-256-GCM Encryption - API keys are encrypted and cannot be read from the plist file
Key Derivation - Encryption keys are derived from organization name + license key

Configuration Options

VoxyAI can be configured via:

MDM Configuration Profile - Deploy settings via Jamf, Mosyle, Kandji, or other MDM solutions
Enterprise Config File - Place a signed configuration file on target machines

MDM Configuration Profile

Create a custom configuration profile with the following domain:

com.voxyai.VoxyAI

Configuration Keys

Key	Type	Description
`OrganizationName`	String	Your organization name (required)
`LicenseKey`	String	Enterprise license key (required)
`EncryptedPayload`	Data	Base64-encoded encrypted payload containing API keys
`PayloadSignature`	Data	Ed25519 signature for verification
`EnforcedAIProvider`	String	Lock users to a specific AI provider (optional)
`AllowUserOverride`	Boolean	Allow users to change settings (default: true)
`DisabledFeatures`	Array	List of features to disable for this organization

Encrypted Payload Contents

The encrypted payload (after decryption) contains:

Key	Type	Description
`apiKeys`	Object	Map of provider names to API keys (anthropic, openai, google, groq, mistral, perplexity)
`allowedModels`	Array	Optional list of allowed model names
`configExpiration`	String	Optional ISO 8601 expiration date for the config

Example Configuration Structure

<?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>OrganizationName</key>
    <string>Acme Corporation</string>
    <key>LicenseKey</key>
    <string>VOXYAI-ENT-XXXX-XXXX-XXXX</string>
    <key>EncryptedPayload</key>
    <data>BASE64_ENCRYPTED_API_KEYS...</data>
    <key>PayloadSignature</key>
    <data>BASE64_ED25519_SIGNATURE...</data>
    <key>EnforcedAIProvider</key>
    <string>anthropic</string>
    <key>AllowUserOverride</key>
    <false/>
</dict>
</plist>

Config File Locations

VoxyAI checks for enterprise configuration in priority order:

/Library/Managed Preferences/com.voxyai.VoxyAI.plist (MDM deployed)
/Library/Application Support/VoxyAI/enterprise-config.plist (local file)

Generating Enterprise Configs

Enterprise configuration files must be generated by VoxyAI using our secure configuration tool. This ensures:

API keys are properly encrypted with AES-256-GCM
Configurations are signed with our private key
Tampered configs are rejected by the app

Security Recommendations

While API keys are encrypted, we recommend additional security measures:

Set spending limits on API keys via provider dashboards
Restrict API keys to office IP ranges where possible
Monitor API usage logs for anomalies
Use separate API keys per department for audit trails
Treat key extraction as a policy violation

IDE Integration

No plugins or extensions needed! VoxyAI works everywhere on your Mac. It uses the system clipboard and paste functionality, so it works with any application - no installation of IDE plugins required.

VoxyAI detects when you are in a code editor and adjusts its behavior accordingly:

Generates properly formatted code blocks
Respects your current language context
Can analyze selected code for fixes or explanations
Generates documentation and comments

Works With Any Application

VoxyAI works with all applications including:

Code editors: VS Code, Xcode, IntelliJ IDEA, PyCharm, Sublime Text, Vim, Emacs
Email clients: Mail, Outlook, Gmail in browser
Communication: Slack, Discord, Messages, Teams
Documents: Pages, Word, Google Docs, Notion
Terminal: Terminal.app, iTerm2, Warp
Any app that accepts text input

Installation

System Requirements

macOS 26 or later
Microphone access
Accessibility permission (for auto-paste)

Required Permissions

VoxyAI requires the following permissions:

Microphone - To capture your voice for dictation
Speech Recognition - To convert speech to text using macOS built-in recognition
Accessibility - To automatically paste formatted text into the active application

Keyboard Shortcuts

Shortcut	Action
`fn + shift`	Start voice recording (hold to record voice)
`fn + ctrl`	Type command (no voice)

Ollama Setup Guide

What is Ollama? Ollama is a free, open-source tool that lets you run large language models locally on your Mac. This means your data stays on your device, you have no API costs, and you can use AI even without an internet connection.

Installing Ollama

Download from ollama.com/download
Open the downloaded .zip file
Drag Ollama to your Applications folder
Open Ollama from your Applications folder
When prompted, click "Open" to allow the app to run (it's from an identified developer)

Note: After installation, Ollama runs as a menu bar application. You'll see a small llama icon in your menu bar when it's running.

Verify Installation

Open Terminal and run:

ollama --version

You should see the version number displayed, confirming Ollama is installed correctly.

Browse Available Models

You can browse all available models on the Ollama library:

ollama.com/library

The library includes models from various providers including Meta (Llama), Google (Gemma), Mistral, DeepSeek, and many more.

Installing Models

Open Terminal and use the pull command:

ollama pull <model-name>

Example: Installing DeepSeek

DeepSeek offers excellent coding and reasoning capabilities. To install it:

ollama pull deepseek-r1

DeepSeek R1 comes in several sizes. You can specify a particular size:

# 7 billion parameters (requires ~5GB RAM)
ollama pull deepseek-r1:7b

# 14 billion parameters (requires ~9GB RAM)
ollama pull deepseek-r1:14b

# 32 billion parameters (requires ~20GB RAM)
ollama pull deepseek-r1:32b

Memory Requirements: Larger models require more RAM. As a general rule, you need about 1GB of RAM for every 1 billion parameters. Choose a model size that fits comfortably within your Mac's available memory.

Recommended Models

DeepSeek R1

Excellent for complex reasoning tasks and code generation. Shows step-by-step thinking process.

ollama pull deepseek-r1

Llama 3.3

Meta's latest model. Great balance of speed and capability for everyday tasks.

ollama pull llama3.3

Qwen 2.5 Coder

Specialized for code generation and programming tasks. Very capable for its size.

ollama pull qwen2.5-coder

Mistral

Fast and efficient model suitable for most general-purpose tasks.

ollama pull mistral

Gemma 2

Google's open model. Available in smaller sizes, good for Macs with limited RAM.

ollama pull gemma2

Memory Requirements

8GB RAM: 7b models or smaller
16GB RAM: 7b-14b models work well
32GB+ RAM: Larger 32b models are usable

Managing Models

List Installed Models

To see all models you have installed:

ollama list

Remove a Model

To free up disk space by removing a model you no longer need:

ollama rm <model-name>

Update a Model

To update to the latest version of a model:

ollama pull <model-name>

Running pull again will download any updates if available.

Using with VoxyAI

Make sure Ollama is running (look for the llama icon in your menu bar)
Open VoxyAI settings
Select "Ollama" as your AI provider
Choose your installed model from the dropdown list
VoxyAI will automatically connect to your local Ollama instance

Tip: Ollama runs on port 11434 by default. VoxyAI connects to http://localhost:11434 automatically. No API key is needed for local models.

Troubleshooting

Ollama not responding

Check if Ollama is running in your menu bar
Try restarting Ollama from the menu bar icon
Run "ollama serve" in Terminal to start it manually

Model runs slowly

Try a smaller model variant (e.g., 7b instead of 14b)
Close other memory-intensive applications
Macs with Apple Silicon (M1/M2/M3/M4) run models much faster than Intel Macs

Not enough memory

Use a smaller model size appropriate for your RAM
For 8GB RAM: stick to 7b models or smaller
For 16GB RAM: 7b-14b models work well
For 32GB+ RAM: larger models like 32b are usable

Terminal Commands

When Terminal is your active application, VoxyAI automatically converts natural language to shell commands.

Examples

You say: "list all files modified in the last week"

find . -type f -mtime -7

You say: "find all Python files containing the word config"

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

Tone Settings

Adjust the tone of your formatted text to match the situation:

Formal

Professional language for business communications

Assertive

Confident, direct communication style

Empathetic

Warm, understanding tone for sensitive topics

Concise

Brief, to-the-point messages

Detailed

Thorough explanations with full context

Humorous

Light-hearted, casual communication

Voice Commands

VoxyAI understands natural language. Just speak normally and the AI will format appropriately. Some special commands:

"translate to [language]" - Translates your text to the specified language
"write a function that..." - Generates code based on your description
"fix this code" - Analyzes and fixes code in your clipboard or selection
"generate a script to..." - Creates a complete script with documentation