Osaurus

Osaurus is the AI edge runtime for macOS.

It runs local and cloud models, exposes shared tools via MCP, and provides a native, always-on foundation for AI apps and workflows on Apple Silicon.

Created by Dinoki Labs (dinoki.ai)

Documentation · Discord · Plugin Registry · Contributing

⚠️ Naming Changes in This Release ⚠️

We've renamed two core concepts to better reflect their purpose:

• Personas are now called Agents — custom AI assistants with unique prompts, tools, and themes.
• Agent Mode is now called Work Mode — autonomous task execution with issue tracking and file operations.

All existing data is automatically migrated. This notice will be removed in a future release.

Install

brew install --cask osaurus

Or download from Releases.

After installing, launch from Spotlight (⌘ Space → "osaurus") or run osaurus ui from the terminal.

What is Osaurus?

Osaurus is the AI edge runtime for macOS. It brings together:

• MLX Runtime — Optimized local inference for Apple Silicon using MLX
• Remote Providers — Connect to Anthropic, OpenAI, OpenRouter, Ollama, LM Studio, or any compatible API
• OpenAI, Anthropic & Ollama APIs — Drop-in compatible endpoints for existing tools
• MCP Server — Expose tools to AI agents via Model Context Protocol
• Remote MCP Providers — Connect to external MCP servers and aggregate their tools
• Plugin System — Extend functionality with community and custom tools
• Agents — Create custom AI assistants with unique prompts, tools, and visual themes
• Skills — Import reusable AI capabilities from GitHub or files (Agent Skills compatible)
• Schedules — Automate recurring AI tasks with timed execution
• Watchers — Monitor folders for changes and trigger AI tasks automatically
• Work Mode — Autonomous task execution with issue tracking, parallel tasks, and file operations
• Multi-Window Chat — Multiple independent chat windows with per-window agents
• Developer Tools — Built-in insights and server explorer for debugging
• Voice Input — Speech-to-text using WhisperKit with real-time on-device transcription
• VAD Mode — Always-on listening with wake-word activation for hands-free agent access
• Transcription Mode — Global hotkey to transcribe speech directly into any app
• Apple Foundation Models — Use the system model on macOS 26+ (Tahoe)

Highlights

| Feature | Description | | ------------------------ | ---------------------------------------------------------------------- | | Local LLM Server | Run Llama, Qwen, Gemma, Mistral, and more locally | | Remote Providers | Anthropic, OpenAI, OpenRouter, Ollama, LM Studio, or custom | | OpenAI Compatible | /v1/chat/completions with streaming and tool calling | | Anthropic Compatible | /messages endpoint for Claude Code and Anthropic SDK clients | | Open Responses | /responses endpoint for multi-provider interoperability | | MCP Server | Connect to Cursor, Claude Desktop, and other MCP clients | | Remote MCP Providers | Aggregate tools from external MCP servers | | Tools & Plugins | Browser automation, file system, git, web search, and more | | Skills | Import AI capabilities from GitHub or files, with smart context saving | | Agents | Custom AI assistants with unique prompts, tools, and themes | | Schedules | Automate AI tasks with daily, weekly, monthly, or yearly runs | | Watchers | Monitor folders and trigger AI tasks on file system changes | | Work Mode | Autonomous multi-step task execution with parallel task support | | Custom Themes | Create, import, and export themes with full color customization | | Developer Tools | Request insights, API explorer, and live endpoint testing | | Multi-Window Chat | Multiple independent chat windows with per-window agents | | Menu Bar Chat | Chat overlay with session history, context tracking (⌘;) | | Voice Input | Speech-to-text with WhisperKit, real-time transcription | | VAD Mode | Always-on listening with wake-word agent activation | | Transcription Mode | Global hotkey to dictate into any focused text field | | Model Manager | Download and manage models from Hugging Face |

Quick Start

1. Start the Server

Launch Osaurus from Spotlight or run:

osaurus serve

The server starts on port 1337 by default.

2. Connect an MCP Client

Add to your MCP client configuration (e.g., Cursor, Claude Desktop):

{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}

3. Add a Remote Provider (Optional)

Open the Management window (⌘ Shift M) → Providers → Add Provider.

Choose from presets (Anthropic, OpenAI, xAI, OpenRouter) or configure a custom endpoint.

Key Features

Local Models (MLX)

Run models locally with optimized Apple Silicon inference:

# Download a model
osaurus run llama-3.2-3b-instruct-4bit

# Use via API
curl http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.2-3b-instruct-4bit", "messages": [{"role": "user", "content": "Hello!"}]}'

Remote Providers

Connect to remote APIs to access cloud models alongside local ones.

Supported presets:

• Anthropic — Claude models with native API support
• OpenAI — ChatGPT models
• xAI — Grok models
• OpenRouter — Access multiple providers through one API
• Custom — Any OpenAI-compatible endpoint (Ollama, LM Studio, etc.)

Features:

• Secure API key storage (macOS Keychain)
• Custom headers for authentication
• Auto-connect on launch
• Connection health monitoring

See Remote Providers Guide for details.

MCP Server

Osaurus is a full MCP (Model Context Protocol) server. Connect it to any MCP client to give AI agents access to your installed tools.

| Endpoint | Description | | ----------------- | ---------------------- | | GET /mcp/health | Check MCP availability | | GET /mcp/tools | List active tools | | POST /mcp/call | Execute a tool |

Remote MCP Providers

Connect to external MCP servers and aggregate their tools into Osaurus:

• Discover and register tools from remote MCP endpoints
• Configurable timeouts and streaming
• Tools are namespaced by provider (e.g., provider_toolname)
• Secure token storage

See Remote MCP Providers Guide for details.

Tools & Plugins

Install tools from the central registry or create your own.

Official System Tools:

| Plugin | Tools | | -------------------- | ------------------------------------------------------------------------- | | osaurus.filesystem | read_file, write_file, list_directory, search_files, and more | | osaurus.browser | browser_navigate, browser_click, browser_type, browser_screenshot | | osaurus.git | git_status, git_log, git_diff, git_branch | | osaurus.search | search, search_news, search_images (DuckDuckGo) | | osaurus.fetch | fetch, fetch_json, fetch_html, download | | osaurus.time | current_time, format_date |

# Install from registry
osaurus tools install osaurus.browser

# List installed tools
osaurus tools list

# Create your own plugin
osaurus tools create MyPlugin --language swift

See the Plugin Authoring Guide for details.

Agents

Create custom AI assistants with unique behaviors, capabilities, and styles.

Each agent can have:

• Custom System Prompt — Define unique instructions and personalit