Installation
Osaurus is a native macOS app for Apple Silicon. The fastest way to get it is the download button on the home page — drag it to Applications and you're done.
System requirements
- macOS 15.5 or later
- Apple Silicon (M1, M2, M3, or newer)
- 2–20 GB free space per local model
The Sandbox (running agent code in an isolated Linux VM) and Apple Foundation Models require macOS 26 (Tahoe) or later. Osaurus itself runs fine on 15.5+ — those features just stay disabled.
Install in 3 steps
- Download the
.dmgfrom osaurus.ai (or GitHub Releases) - Open the DMG and drag Osaurus into your Applications folder
- Eject the DMG and launch Osaurus from Spotlight (
⌘ Space→ "Osaurus")
The first time you open it, macOS may show a security dialog because the app is signed but not yet notarized — right-click Osaurus.app and choose Open, then click Open in the dialog. You only need to do this once.
That's it. Updates auto-install via Sparkle when you launch the app — no need to come back here.
Prefer the terminal?
If you'd rather install via Homebrew:
brew install --cask osaurus
This puts Osaurus.app in your Applications folder and links the osaurus CLI into your PATH. Update with brew upgrade --cask osaurus.
Permissions
Osaurus only asks for permissions when you actually use the feature that needs them:
| Permission | Needed for |
|---|---|
| Microphone | Voice input, wake-word activation, Transcription Mode |
| Screen Recording | Capturing system audio for transcription |
| Accessibility | Transcription Mode (typing into other apps) |
| Network | Cloud providers, MCP, public agent links |
| Files | Working folders (one folder at a time, via macOS security-scoped bookmarks) |
You'll be prompted in System Settings → Privacy & Security as you use each feature.
Where Osaurus puts things
| What | Path |
|---|---|
| Local models (MLX) | ~/MLXModels/ (override with OSU_MODELS_DIR) |
| App data | ~/.osaurus/ |
| Voice models | ~/Library/Application Support/FluidAudio/Models/ |
| Encrypted databases | ~/.osaurus/{chat-history,memory,methods,tool-index}/*.sqlite |
| Encryption key | macOS Keychain (com.osaurus.storage) |
To put models on an external drive:
export OSU_MODELS_DIR=/Volumes/External/MLXModels
Verify the CLI
If you installed via DMG and want to use the osaurus CLI from the terminal:
osaurus --version
osaurus serve # starts the local server
osaurus status # confirms it's up
osaurus stop # stops it
If osaurus isn't on your PATH (DMG install), link it once:
ln -sf "/Applications/Osaurus.app/Contents/MacOS/osaurus" "$(brew --prefix)/bin/osaurus"
Or add the bundle to your shell:
echo 'export PATH="/Applications/Osaurus.app/Contents/MacOS:$PATH"' >> ~/.zshrc
source ~/.zshrc
Test the local server is up:
curl http://127.0.0.1:1337/health
Troubleshooting
"Cannot be opened" error
System Settings → Privacy & Security → scroll to the security message → Open Anyway.
osaurus command not found
See the link/PATH steps in Verify the CLI.
Storage migration "failed" notice
If the first-launch migration shows a partial failure, the originals are kept at ~/.osaurus/.pre-encryption-backup/. Open Settings → Storage for recovery options. Full guide →
Uninstall
# If you installed via Homebrew
brew uninstall --cask osaurus
# If you installed manually
rm -rf /Applications/Osaurus.app
rm /usr/local/bin/osaurus 2>/dev/null
# Optional: remove all your data
rm -rf ~/MLXModels
rm -rf ~/.osaurus
# Optional: remove the storage encryption key from Keychain
security delete-generic-password -s com.osaurus.storage -a data-encryption-key
Removing ~/.osaurus and the Keychain entry is irreversible. Use Settings → Storage → Export plaintext backup first if you want to keep your chats and memory.
Next: Quick Start → — your first conversation in 5 minutes.