Osaurus

Osaurus is a native macOS application that acts as a personal AI harness, sitting between you and any language model — local or cloud — to provide the continuity layer that makes AI genuinely personal. Built entirely in Swift for Apple Silicon, it runs fully offline with on-device MLX models and connects to cloud providers like OpenAI, Anthropic, and Gemini when you want more power.

At its core, Osaurus gives AI agents persistent memory, autonomous execution, isolated sandbox environments, and cryptographic identity — all running on your Mac. The memory system uses a three-layer architecture (identity, pinned facts, episodic digests) with salience scoring and background consolidation, injecting only what’s relevant rather than flooding context windows. The sandbox feature uses Apple’s Containerization framework to give agents full Linux development environments (shell, Python, Node.js, compilers) that are isolated from your Mac but still connected back to Osaurus for inference and memory via vsock bridges.

The cryptographic identity system assigns every participant — human, agent, or device — a secp256k1 address. Agent-to-agent communication uses forward-secret X25519 handshakes with ChaCha20-Poly1305 framing, meaning even if long-term keys are later compromised, recorded sessions remain private. A built-in relay service exposes agents to the internet via WebSocket tunnels without port forwarding.

Osaurus also serves as a full MCP (Model Context Protocol) server, exposing all agent tools to any MCP-compatible client, while also acting as an MCP aggregator for remote providers like GitHub, Linear, Notion, and Stripe. The plugin ecosystem supports 20+ native plugins and a v3 plugin API with hot reload, per-plugin SQLite storage, and Swift or JSON-defined recipes.

What You Get

• Local MLX inference — Run Gemma 4, Qwen3, Llama, GPT-OSS, and other models on Apple Silicon using the vmlx-swift runtime with quantizations curated by Osaurus for quality-to-size ratio, stored at ~/MLXModels.
• Persistent AI memory — A three-layer on-device memory system (identity, pinned facts, episodic digests) with salience scoring, decay, and background consolidation that injects ~800 tokens of relevant context per turn, not a firehose of everything.
• Isolated sandbox execution — Agents run shell commands, Python, Node.js, and compilers in an isolated Alpine Linux VM powered by Apple’s Containerization framework, connected back to Osaurus for inference via a vsock bridge, with zero risk to your Mac.
• Cryptographic agent identity — Every participant gets a secp256k1 address with a verifiable chain of trust from your master iCloud Keychain key. Create scoped access keys (osk-v1), revoke them anytime, and pair agents for encrypted direct communication.
• End-to-end encrypted agent channels — Forward-secret X25519 handshakes authenticated by secp256k1 agent keys, with all traffic sealed in ChaCha20-Poly1305 with anti-replay sequence numbers. The relay is a blind pipe that cannot read your messages.
• Privacy filter — An on-device 1.5B-parameter sparse MoE classifier detects names, emails, phones, credentials, and custom patterns before any cloud send, with a scrubbed preview and fail-closed blocking if anything leaks post-scrub.
• MCP server and client — Expose all agent tools to any MCP-compatible client via stdio bridge, and aggregate tools from 25+ remote HTTP/SSE MCP providers including GitHub, Linear, Notion, Stripe, and Cloudflare with auto OAuth 2.1.
• 20+ native plugins — Mail, Calendar, Vision, Browser, Git, XLSX, PPTX, Music, Filesystem, Search, Fetch, and more, with a v3 plugin API that supports HTTP routes, web apps, per-plugin SQLite, and hot reload in development.

Common Use Cases

• Private AI development assistant — A developer configures a coding agent with file and git tools in a working folder, uses the sandbox for running test suites, and relies on memory to track ongoing decisions across sessions, all without sending code to cloud servers.
• Multi-provider AI workstation — A researcher switches freely between Apple Foundation Models for privacy-sensitive work, local MLX models for offline operation, and Anthropic or OpenAI for tasks requiring frontier capability, with a single chat UI and persistent memory across all providers.
• Autonomous scheduled workflows — A founder sets up schedule-driven agents that fetch industry news, synthesize summaries using a local model, and push results to a Notion page via MCP — running silently on their Mac overnight with no cloud orchestration.
• MCP tool aggregation hub — A team uses Osaurus as their local MCP server, connecting Claude Desktop and other clients to a unified set of tools spanning GitHub, Linear, Stripe, and custom file-system plugins without managing separate credentials for each client.
• Privacy-conscious AI writing — A journalist uses Osaurus with the privacy filter enabled to draft articles with AI assistance, confident that names, sources, and sensitive details are scrubbed before any cloud model sees them, with full control over what gets approved.
• Agent-to-agent automation — An advanced user pairs two Osaurus instances across their home network, allowing a research agent on one Mac to delegate file-processing tasks to a sandbox agent on another, with all traffic end-to-end encrypted through the relay.

Under The Hood

Architecture Osaurus follows a rigorously enforced three-layer architecture inside the OsaurusCore Swift package: Models as pure immutable data structs with no side effects, Services as Swift actors or stateless structs implementing business logic without UI awareness, and Managers as MainActor-bound observable classes that bridge services to SwiftUI. The architecture guide codifies which layer each abstraction belongs in, with explicit rules — services never conform to ObservableObject, models never hold singletons. The inference subsystem routes requests through a ModelServiceRouter with circuit breakers, retry logic, and timeout handling, dispatching to FoundationModelService, MLXService, or RemoteProviderService based on model identifier. The memory subsystem uses a write-debounce pattern — turns are buffered without LLM calls, and distillation is a single LLM call per session rather than per turn. The sandbox uses Apple’s Containerization framework to provision isolated Linux VMs with per-agent home directories connected back to Osaurus via vsock bridges, enabling full code execution without network exposure.

Tech Stack The entire macOS application and its packages are written in Swift 6 with strict concurrency, using SwiftUI for the interface and AppKit for system integration. Local model inference runs through vmlx-swift, a consolidated package vendoring MLX, MLXLLM, MLXVLM, Tokenizers, and Jinja for Apple Silicon. The MCP implementation uses the official swift-sdk from modelcontextprotocol. Networking is built on SwiftNIO with EventSource for SSE streaming. Cryptographic identity uses secp256k1 via swift-secp256k1 and standard CryptoKit for X25519 and ChaCha20-Poly1305. Vector search for memory and skill RAG uses VecturaKit with embeddings from vmlx-swift. Storage is SQLite with SQLCipher for encrypted databases, with the app using Sparkle for updates, Aptabase for anonymous telemetry, and Sentry for crash reporting behind an opt-in consent gate.

Code Quality The codebase demonstrates consistent engineering discipline throughout. Swift 6 strict concurrency is enforced project-wide, with extensive actor isolation preventing data races at compile time. Test coverage spans extensive unit tests for the memory subsystem, identity cryptography, MCP routing, plugin infrastructure, and CLI coordination, with a dedicated OsaurusEvals package for model output quality assessment. Error handling uses typed enums with LocalizedError conformance and circuit breaker patterns at service boundaries. The CI pipeline includes a launch gate that verifies the signed binary can actually spawn before a release ships, catching entitlement regressions that would otherwise brick a release. Inline documentation is thorough, with design intent, invariants, and non-obvious decisions annotated in code comments throughout the core services.

What Makes It Unique Osaurus occupies a genuinely novel position as the only native Swift macOS application that combines on-device MLX inference, cryptographic agent identity with forward-secret agent-to-agent encryption, Apple Containerization-based sandbox execution, and a three-layer salience-scored memory system into a unified harness. The privacy filter is architecturally unusual — it uses an on-device sparse MoE model to detect PII before cloud sends, with fail-closed semantics where a post-scrub detection blocks the send entirely rather than proceeding with uncertainty. The identity system generates a verifiable chain of trust from an iCloud Keychain master key down to per-agent scoped access keys, making agent authority both auditable and revocable. The relay exposes agents via WebSocket tunnels keyed to their crypto addresses, meaning agent endpoints are intrinsically authenticated by the same identity chain.

Self-Hosting

Osaurus is released under the MIT License, which is one of the most permissive open-source licenses available. This means you can use it commercially, modify the source code, distribute it, and sublicense it with no restrictions. There are no copyleft obligations — your modifications do not need to be open-sourced, and there is no viral licensing effect on any code you build on top of Osaurus. The only requirement is preserving the copyright notice in distributions.

Running Osaurus yourself requires Apple Silicon hardware running macOS 15.5 or newer, with macOS 26 (Tahoe) required for the sandbox and Apple Foundation Models features. Since it is a native macOS app, there is no server infrastructure to provision or maintain — the entire harness runs on the local machine. Updates are handled via Sparkle, and you are responsible for keeping the app current since there is no managed update mechanism in self-built versions. For teams deploying across multiple machines, the Shared Configuration feature allows pushing settings from a central source, but there is no enterprise directory integration or centralized management console.

Compared to hosted AI platforms, Osaurus trades SLAs, managed uptime, and cloud-backed redundancy for complete data sovereignty and privacy. There is no commercial cloud tier or support plan — the community Discord and GitHub issues are the primary support channels. For teams that need guaranteed response times, enterprise support agreements, or regulated-data compliance certifications, Osaurus in its current form requires self-assessment. The privacy filter and fully offline capability make it well-suited for sensitive workloads, but the operational burden of managing model downloads, key backup, and software updates falls entirely on the operator.