Skip to main content

Installation

Osaurus is available as a native macOS application for Apple Silicon. Choose your preferred installation method.

System Requirements​

  • macOS 15.5 or later
  • Apple Silicon (M1, M2, M3, or newer)
  • 2-20GB free space per model
Apple Foundation Models

Apple Intelligence features require macOS 26 (Tahoe) or later with Apple Intelligence enabled in System Settings.

Homebrew Installation​

The recommended installation method:

brew install --cask osaurus

This installs:

  • Osaurus.app in your Applications folder
  • CLI via the osaurus command (automatically linked)
  • Automatic updates through brew upgrade

First Launch​

After installing:

  1. Launch from Spotlight (⌘ Space → "osaurus") or run osaurus ui
  2. Look for the Osaurus icon in your menu bar
  3. Click the icon to access controls

Updating via Homebrew​

# Update Homebrew formulae
brew update

# Upgrade Osaurus
brew upgrade --cask osaurus

Direct Download​

Download the latest signed build from GitHub:

  1. Visit GitHub Releases
  2. Download the DMG file
  3. Open the DMG and drag Osaurus to Applications
  4. Eject the DMG

First Launch (Direct Download)​

When launching for the first time:

  1. Right-click Osaurus.app and select Open
  2. Click Open in the security dialog
  3. Grant necessary permissions when prompted
note

This step is only required once. Osaurus is properly signed but not notarized.

Manual CLI Setup​

After installing via direct download, set up the CLI:

# Create symlink to CLI
sudo ln -sf /Applications/Osaurus.app/Contents/MacOS/osaurus /usr/local/bin/osaurus

# Verify installation
osaurus --version

Or add to PATH:

echo 'export PATH="/Applications/Osaurus.app/Contents/MacOS:$PATH"' >> ~/.zshrc
source ~/.zshrc

Building from Source​

For development or customization, build from source.

Prerequisites​

  • Xcode 16.4 or later
  • Command Line Tools
  • Git

Build Process​

# Clone the repository
git clone https://github.com/dinoki-ai/osaurus.git
cd osaurus

# Open in Xcode
open osaurus.xcworkspace

# Build and run the "osaurus" scheme
# Or use Xcode: Product → Build (⌘B)

The built app will be in your Xcode derived data folder.

Command Line Build​

# Build release configuration
xcodebuild -workspace osaurus.xcworkspace -scheme osaurus -configuration Release

# The output path is shown at the end of the build

Installation Verification​

Verify your installation:

# Check CLI version
osaurus --version

# Test server startup
osaurus serve

# In another terminal, check status
osaurus status

# Stop server
osaurus stop

GUI Verification​

  1. Launch Osaurus from Applications or Spotlight
  2. Look for the menu bar icon
  3. Click the icon and select About
  4. Verify the version number

Model Storage​

Models are stored at:

~/MLXModels

Override with the OSU_MODELS_DIR environment variable:

export OSU_MODELS_DIR=/Volumes/External/MLXModels

Permissions​

Osaurus requires minimal permissions:

  • Network Access — For serving the local API
  • File System Access — For model storage and tools

Some tools may require additional permissions:

  • Automation — For AppleScript-based tools
  • Accessibility — For UI automation tools

Grant these in System Settings → Privacy & Security when prompted.

Troubleshooting​

"Cannot be opened" Error​

If macOS prevents opening Osaurus:

  1. Go to System Settings → Privacy & Security
  2. Find Osaurus in the security section
  3. Click Open Anyway

CLI Not Found​

If the osaurus command isn't recognized:

# Check if app exists
ls /Applications/Osaurus.app/Contents/MacOS/osaurus

# Create symlink manually
ln -sf "/Applications/Osaurus.app/Contents/MacOS/osaurus" "$(brew --prefix)/bin/osaurus"

Permission Denied​

If you get permission errors:

# Make CLI executable
chmod +x /Applications/Osaurus.app/Contents/MacOS/osaurus

# Use without sudo for normal operations
osaurus serve  # Correct

Uninstallation​

Via Homebrew​

brew uninstall --cask osaurus

Manual Uninstallation​

  1. Quit Osaurus from the menu bar

  2. Delete the application:

    rm -rf /Applications/Osaurus.app

  3. Remove CLI symlink:

    rm /usr/local/bin/osaurus

  4. Optional — Remove data:

    # Models
    rm -rf ~/MLXModels

    # App data and tools
    rm -rf ~/Library/Application\ Support/com.dinoki.osaurus

Next Steps​

Once installed:

For installation help, visit our Discord community or check the GitHub issues.