Osaurus: A Native macOS Harness for Offline AI Agents with Sandboxed Execution and Cryptographic Identity

What Osaurus Solves and Who It Is For

Osaurus addresses a specific gap in the AI tooling landscape: the layer around models, namely context, memory, tools, and identity, is usually held on someone else's servers. The README states that models are interchangeable, but the harness is what compounds. Osaurus keeps that layer on your Mac. It is for engineers and power users who want agents that remember past conversations, execute code autonomously, and maintain a verifiable identity, all without sending data to a cloud service unless they explicitly choose to. The project targets macOS users with Apple Silicon, requiring macOS 15.5 or later, and it is built natively in Swift with no Electron. This is a deliberate choice for performance and integration with the operating system, but it also means the tool is strictly limited to one platform.

The Agent Loop and Orchestrator Exception

The core mechanism is the agent loop. A custom agent picks a working folder and gets file, search, and git tools. With the sandbox toggled on, it also gets shell access inside an isolated environment. The model writes a markdown todo list, executes against it, and closes out with a verified summary, all within the same chat window. This is a structured workflow that forces the agent to plan and report, rather than improvise. The built-in Orchestrator is the exception: it has no working folder, sandbox, browser, or computer use. That means if you need filesystem work, you must create or switch to a custom agent. This is a clear design trade-off: the Orchestrator is likely meant for high-level coordination, but the documentation does not detail what it actually does beyond being an exception. Users should not expect the Orchestrator to handle file operations.

Sandbox Execution: Linux VM vs Seatbelt Fallback

Sandboxing is where Osaurus shows its most interesting engineering. Agents execute code in an isolated Linux VM powered by Apple's Containerization framework. The VM runs Alpine Linux, and each agent gets its own Linux user and home directory. The VM connects back to Osaurus via a vsock bridge, so it is sandboxed but not disconnected. This allows inference, memory, and secrets to flow between the host and the VM. The README includes a diagram showing the sandbox manager on the host communicating with the VM over vsock, with VirtioFS mounting the workspace. A critical constraint: the Linux VM requires macOS 26+ (Tahoe). On earlier versions, Osaurus falls back to a native macOS Seatbelt sandbox using sandbox-exec. That fallback is more limited: commands run on your Mac, writes are confined to the sandbox workspace, pip and npm installs work but not apk, and network access is all-or-nothing instead of per-domain. This is a significant limitation for anyone not on Tahoe, as per-domain network control is a common requirement for security-conscious users.

Memory Architecture and Token Efficiency

Memory is handled in three layers: identity, pinned facts, and per-session episodes, plus a transcript fallback. Agents distill conversations once at session end, not on every turn, and score what matters by salience. At most one compact slice is surfaced per request, based on what you are asking. A background consolidator decays, merges, and evicts to keep memory sharp. The claimed token cost is modest: most turns inject about 800 tokens or less, and many inject zero. This is a deliberate design to avoid bloating the context window. The trade-off is that memory is lossy by design; the consolidator decides what to keep, which could drop details you later need. The documentation does not specify how to retrieve evicted memories, so users should assume that once something is decayed, it is gone.

Privacy Filter and Fail-Closed Behavior

For cloud model use, Osaurus includes a privacy filter that runs on-device. It uses OpenAI's openai/privacy-filter model, a 1.5B parameter sparse-MoE, served via an MLX conversion. The filter detects names, emails, phones, URLs, addresses, dates, account numbers, and free-form secrets, alongside deterministic regex for SSN, credit cards, IBAN, AWS keys, and GitHub tokens. Each detection is shown in a review sheet with a scrubbed preview before sending. Approved entities are swapped for stable placeholders like [PERSON_1] and [EMAIL_2], and streaming replies are unscrubbed on the fly so the chat reads naturally. The system is fail-closed: if the post-scrub scan finds anything that leaked, the send is blocked. This is a strong guarantee, but it comes at a cost: the model is about 2.8 GB, which is a significant download. Users should verify wire-level redaction in the Insights panel, which captures the exact bytes the cloud saw. This is a concrete way to test the filter's effectiveness.

Identity and Relay: Cryptographic Control

Identity is built on secp256k1 cryptographic addresses for every participant: human, agent, and device. Authority flows from a master key stored in iCloud Keychain down to each agent in a verifiable chain of trust. You can create portable access keys with the osk-v1 prefix, scope them per agent, and revoke them anytime. This gives you a way to delegate access without sharing a master password. The Relay feature exposes agents to the internet, though the README is truncated at that point, so the exact mechanism is not fully described. Based on the identity system, it likely uses those access keys for authentication, but this is not confirmed. Users should check the identity documentation for specifics before relying on remote access.

Installation, Commands, and Storage

Installation is straightforward: brew install --cask osaurus, or download the latest .dmg from the releases page. After installation, you launch from Spotlight or use the CLI. The commands are simple: osaurus ui opens the chat UI, osaurus serve starts the server, and osaurus status checks status. Storage is plaintext by default, protected by FileVault, with opt-in SQLCipher encryption. This is a notable choice: plaintext means your data is readable if someone gains access to your Mac, even if FileVault is on at rest. The opt-in encryption is a step up, but it is not the default. For sensitive data, you should enable SQLCipher. The project is MIT licensed, which is permissive, but you should check the license file for any specific terms. Maintenance and upgrade cost: the project is actively updated, with recent releases 0.24.0 through 0.24.2 in late August 2026. That suggests a fast release cadence, which can mean frequent changes. Users should monitor the changelog for breaking changes, especially around the sandbox and privacy filter.

Limitations and Wrong Tool Cases

Osaurus is not the right tool if you need cross-platform support; it is macOS only, requiring Apple Silicon. It is also not ideal if you are on macOS versions before Tahoe and need per-domain network control in the sandbox, because the fallback only offers all-or-nothing network access. The privacy filter adds a heavy local model, which may be overkill for users who never send data to cloud models. The memory system's lossy nature could be a problem for users who need exact transcripts; the transcript fallback exists, but the consolidation process may still lose details. Finally, the Orchestrator's lack of filesystem tools means you cannot use it for file operations, which might surprise users expecting a general-purpose agent. For a truly different approach, consider a tool like Ollama, which also runs models locally but does not provide the same agent harness, memory, or identity layer. Ollama focuses on model serving, while Osaurus focuses on the surrounding infrastructure. The difference is in scope: Osaurus is a full harness, whereas Ollama is a runtime.

Editorial conclusion

Adopt Osaurus if you are a macOS user on Apple Silicon who wants AI agents that run fully offline, keep memory and identity on your machine, and execute code in an isolated sandbox. Avoid it if you need Windows or Linux support, require per-domain network allowlists on macOS versions before Tahoe, or expect a mature ecosystem of plugins. Before adopting, verify that your model workflow supports the privacy filter's fail-closed behavior, test the fallback sandbox on your macOS version, and review the storage encryption options (plaintext by default, SQLCipher opt-in) to ensure they meet your requirements.

Official sources

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