Osaurus: A Native macOS Harness for Local and Cloud AI Agents

Agents and Memory That Live on Your Mac, Not a Cloud Provider

Osaurus addresses a problem with current AI agent platforms: the agent's memory, context, and state live on a cloud provider's servers, not on the user's machine. The mission is to "Own your AI." Osaurus keeps agents, memory, tools, and identity on your Mac, running locally or talking to any cloud model you choose. Nothing leaves your device unless you explicitly choose to send it. This is for users who care about data privacy, want to avoid vendor lock-in, or need to work offline. Agents run continuously, remember across sessions, and execute code in a sandbox without touching the internet.

Install via Homebrew or Download the Bundled Model Build

Osaurus requires macOS 15.5 and Apple Silicon. Install via Homebrew:

brew install --cask osaurus

Or download a `.dmg` from the releases page. Two builds are available: the standard build (~70 MB) lets you select a model during onboarding, and a full build (~4 GB) ships with Raptor 0.6 bundled. After installation, launch from Spotlight or the CLI:

osaurus ui       # Open chat UI
osaurus serve    # Start server
osaurus status   # Check status

The full build installs the model into ~/MLXModels on first launch and skips the download, so you can chat offline immediately. Updates afterwards use the small build.

Agents and the Agent Loop

Agents are the core of Osaurus. Each agent gets its own prompts, memory, and visual theme. Agents can be built for research, coding, or file organization. When you define an agent, you pick a working folder and choose tools: file browsing, git integration, search, or shell access. Tools are automatically selected via RAG search based on the task, with no manual configuration. The agent runs a loop: the model writes a markdown todo list, executes against it, and produces a verified summary, all in one chat window. The built-in Orchestrator agent has no working folder, sandbox, or code execution; it is for planning only. For filesystem work, switch to a custom agent.

Sandboxed Code Execution

When an agent runs code, it executes in an isolated Linux VM using Apple's Containerization framework, available on macOS 26+ (Tahoe). Each agent gets its own Linux user and home directory. The sandbox includes a full dev environment: shell, Python, Node.js, compilers, and package managers, with zero risk to your Mac. Code in the sandbox connects back to Osaurus for inference, memory, and secrets via a vsock bridge. On earlier macOS versions, Osaurus falls back to a native macOS Seatbelt sandbox running code on your Mac under `sandbox-exec`, with writes limited to the sandbox workspace and all-or-nothing network access. You can extend the sandbox with JSON plugin recipes without Xcode or code signing.

Memory and Context Management

Osaurus implements a three-layer memory system: identity, pinned facts, and per-session episodes, with a transcript fallback. Agents distill conversations once at session end (not on every turn) and score what matters by salience. Most turns inject roughly 800 tokens of memory or less; many inject zero. A background consolidator decays, merges, and evicts old memory so it stays sharp instead of growing unbounded. This approach keeps context lean: the harness compounds value through reuse, not through token bloat. Sessions and agents are persistent; you can schedule an agent to run autonomously at a specific time.

Privacy Filtering for Cloud Models

When you send a request to a cloud model, Osaurus runs an on-device privacy classifier before transmission. The filter uses OpenAI's `openai/privacy-filter` (Apache-2.0 license, 1.5B parameters) served via `mlx-community/openai-privacy-filter-bf16`, which detects names, emails, phone numbers, URLs, addresses, dates, account numbers, and free-form secrets. It also applies deterministic regex for SSN, credit cards, IBAN, AWS keys, and GitHub tokens. Before sending, a review sheet shows all detections with a scrubbed preview. You approve which entities to send; the rest are replaced with stable placeholders. Custom patterns are supported. This filter runs locally, so no data leaves your Mac without your consent.

When Osaurus Is the Wrong Choice

Osaurus is macOS and Apple Silicon only. If you need Windows or Linux support, it is not an option. The bundled model (Raptor 0.6, 4 billion parameters) is a small language model; its reasoning abilities are limited compared to much larger models. If you need GPT-4 level capabilities for complex coding or analysis, you will either have to send requests to a cloud API (which Osaurus supports) or build a custom agent that calls an external provider. Model performance, latency, and token limits are best discovered by using it. Storage is plaintext by default (protected by FileVault) with optional SQLCipher encryption; if you require hardware-backed encryption at rest, check your hardware capabilities.

Comparison with Ollama and LM Studio

Ollama and LM Studio are local model runners: you load a model, chat with it, and talk to it via an HTTP API. They are lightweight and model-agnostic. Osaurus is a harness: it sits between you and a model and adds persistent memory, agent loops, code execution, privacy filtering, and identity. You can use Osaurus with Ollama or a cloud API as your backend. Ollama gives you a model; Osaurus gives you an AI partner. If you just need to run a local model and chat, Ollama is simpler. If you need agents that remember, execute code, and respect your privacy, Osaurus layers those on top.

Editorial conclusion

Osaurus is for macOS users who want to run AI agents locally with persistent state and code execution, and who control their own data and don't want it sent to cloud providers. Adopt it if you have Apple Silicon and want an alternative to cloud-only agents. Skip it if you need Windows or Linux support, or if you require the latest large models. Verify that the macOS version supports your hardware and that the model selection meets your needs. The README mentions Raptor 0.6 (4B parameters) as the bundled default; its capabilities may be limited compared to larger models.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes