Skip to content
/
Tier B A12 UI passthrough

OSAURUS

osaurus · osaurus-ai/osaurus · ★ 5.5k · last commit 2026-05-26

Native macOS AI harness with Apple Container Linux VM sandboxing, on-device privacy filter, MLX inference, and cryptographic identity.

Best whenThe layer around AI models (context, memory, tools, identity) is irreplaceable — it must live on your machine, not a vendor's server.
Skip ifForced thinking tags or parser repair (fake coherence), Replacing model-native generation config with synthetic defaults
vs seeds
agent-osis the closest in philosophy (personal harness) but OSAURUS is orders of magnitude more sophisticated: native Swift macO…
Primitive shape 1 total
MCP tools 1
00

Summary

OSAURUS — Summary

OSAURUS is a native macOS AI harness written in Swift for Apple Silicon, positioning itself as the layer that makes AI personal and persistent: "Inference is all you need. Everything else can be owned by you." The project ships a SwiftUI desktop app (downloadable as a .dmg) that combines local MLX model inference, cloud API connections (OpenAI, Anthropic, Gemini, xAI, Venice AI, Ollama, LM Studio), an Apple Container-based Linux VM sandbox for safe code execution, a three-tier memory system with salience scoring, a full MCP server/client, cryptographic identity (secp256k1 key chain), and a WebSocket relay for remote agent access. The privacy filter uses Apple's on-device openai/privacy-filter model to detect and scrub PII before any data leaves the device. The sandbox is built on Apple's Containerization framework (macOS 26+), giving each agent a dedicated Linux user in an Alpine VM connected back to Osaurus via vsock bridge. OSAURUS ships a osaurus CLI binary with subcommands (ui, serve, status, mcp).

Differs from seeds: OSAURUS has no equivalent in the seeds. Its closest relative is agent-os (personal harness philosophy) but OSAURUS is orders of magnitude more sophisticated: native Swift app vs bash scripts, Apple Silicon MLX inference, Apple Container Linux VM sandboxes, secp256k1 cryptographic identity, and a privacy filter. Unlike ccmemory (Neo4j + Claude Code plugin), OSAURUS is a complete standalone macOS application. Unlike superpowers (skills pack), OSAURUS replaces the runtime layer entirely.

01

Overview

OSAURUS — Overview

Origin

OSAURUS is developed by the osaurus-ai team. Built natively in Swift for Apple Silicon, requiring macOS 15.5+. MIT licensed. The name "OSAURUS" reflects the "Own your AI" philosophy — the AI harness is your own, living on your Mac.

Core Philosophy (verbatim from README)

"Own your AI."

"Agents, memory, tools, and identity that live on your Mac. Built purely in Swift. Fully offline. Open source."

"Inference is all you need. Everything else can be owned by you."

"Models are getting cheaper and more interchangeable by the day. What's irreplaceable is the layer around them -- your context, your memory, your tools, your identity. Others keep that layer on their servers. Osaurus keeps it on your machine."

"Works fully offline with local models. Connect to any cloud provider when you want more power. Nothing leaves your Mac unless you choose."

Key Design Choices

  • Model-agnostic: Swap models freely — agents, memory, and tools stay intact
  • Native Swift on Apple Silicon: No Electron, no compromises
  • Privacy filter: On-device PII detection before any cloud send
  • Cryptographic identity: Every participant (human/agent/device) gets a secp256k1 address
  • Sandbox by Apple Container: Linux VM via Apple's Containerization framework (macOS 26+)

Repo Facts

  • GitHub: https://github.com/osaurus-ai/osaurus
  • Stars: 5,509 (2026-05-26)
  • Language: Swift
  • License: MIT
  • Platform: macOS 15.5+ (Apple Silicon)
  • Install: brew install --cask osaurus or download .dmg
02

Architecture

OSAURUS — Architecture

Distribution

  • Desktop app: brew install --cask osaurus or download .dmg from GitHub Releases
  • CLI: osaurus binary (subcommands: ui, serve, status, mcp)
  • Platform: macOS 15.5+ (Apple Silicon required)
  • Sandbox: macOS 26+ (Tahoe) required for Apple Container Linux VM

Core Architecture

┌────────────────┐       ┌────────────────────────────┐
│    Osaurus     │       │   Linux VM (Alpine)        │
│   (macOS app)  │       │                            │
│  Sandbox Mgr ──┼───────┤→ /workspace  (VirtioFS)    │
│  Host API   ←──┼─vsock─┤→ osaurus-host bridge       │
│                │       │                            │
│                │       │  agent-alice  (Linux user) │
│                │       │  agent-bob    (Linux user) │
└────────────────┘       └────────────────────────────┘
  • Alpine Linux VM powered by Apple's Containerization framework
  • Each agent gets its own Linux user and home directory
  • Full dev environment in VM: bash, Python, Node.js, compilers, package managers
  • vsock bridge connects VM back to Osaurus (inference, memory, secrets)

Subsystems

Subsystem Description
MLX Inference Local LLM inference on Apple Silicon via MLX
Sandbox Apple Container Linux VM with vsock bridge
Memory Three-tier: identity + pinned + episodes
Privacy Filter On-device PII detection (1.5B sparse MoE model)
Identity secp256k1 key chain, iCloud Keychain master key
MCP Full MCP server + client with OAuth 2.1
Relay WebSocket tunnel via agent.osaurus.ai

Supported Models

Local (MLX on Apple Silicon)

  • Gemma 4, Qwen3.6, GPT-OSS, Llama, Liquid LFMs
  • Stored at ~/MLXModels
  • Curated models at HuggingFace OsaurusAI org

Apple Foundation Models

  • Available on macOS 26+
  • Zero inference cost, fully private

Cloud

  • OpenAI, Anthropic, Gemini, xAI/Grok, Venice AI, OpenRouter, Ollama, LM Studio

Directory Structure

osaurus/
├── App/         # SwiftUI app
├── Packages/    # Swift Package Manager packages
├── sandbox/     # Sandbox Dockerfile (Alpine Linux)
├── scripts/     # Build/test scripts
├── docs/        # Documentation
│   ├── MEMORY.md
│   ├── SANDBOX.md
│   ├── IDENTITY.md
│   ├── PRIVACY_FILTER.md
│   ├── AGENT_LOOP.md
│   └── REMOTE_MCP_PROVIDERS.md
└── assets/      # Screenshots, icons
03

Components

OSAURUS — Components

CLI Binary (osaurus)

Subcommands:

  • osaurus ui — Open the chat UI
  • osaurus serve — Start the server
  • osaurus status — Check status
  • osaurus mcp — Start stdio MCP server (bridges to local Osaurus HTTP server)

Agents

Each agent in Osaurus has:

  • Own prompts (system prompt)
  • Own memory (isolated by default)
  • Own visual theme
  • Optional private encrypted database
  • Optional self-scheduled next run

Sandbox (Linux VM)

  • Built on Apple Containerization framework (macOS 26+)
  • Alpine Linux image (sandbox/Dockerfile)
  • Pre-installed: bash, Python 3, Node.js, compilers, package managers, git, jq, tar, uv/uvx
  • Each agent gets dedicated Linux user + home directory
  • VirtioFS mount for workspace
  • vsock bridge back to Osaurus host API

Memory System

Three tiers:

  1. Identity files — Consistent personality, preferences across sessions
  2. Pinned facts — Explicitly retained facts
  3. Per-session episodes — Conversation history with transcript fallback

Operations:

  • Background consolidator (decays, merges, evicts)
  • Session-end distillation (not per-turn)
  • Salience scoring
  • ~800 token injection budget per request; inject zero when not needed

Privacy Filter

  • Model: openai/privacy-filter (Apache-2.0, 1.5B sparse MoE, 50M active)
  • MLX conversion: mlx-community/openai-privacy-filter-bf16 (~2.8 GB)
  • Detects: names, emails, phones, URLs, addresses, dates, account numbers, SSN, credit cards, IBAN, AWS keys, GitHub tokens, custom patterns
  • Review sheet shown before cloud send with scrubbed preview
  • Placeholders: [PERSON_1], [EMAIL_2] — unscrubbed on streaming reply
  • Fail-closed: post-scrub scan finds leak → send blocked
  • Insights panel shows exact bytes the cloud saw

Identity System

  • secp256k1 cryptographic address per participant (human/agent/device)
  • Authority chain: iCloud Keychain master key → agent keys
  • Portable access keys (osk-v1), scoped per-agent, revocable

MCP (Model Context Protocol)

  • Osaurus IS a full MCP server (osaurus mcp starts stdio server)
  • Also acts as MCP client: aggregates tools from URL-based remote MCP providers
  • One-tap connect to ~25 providers (Linear, Notion, GitHub, Vercel, Supabase, Sentry, Stripe, Cloudflare, ...) with auto OAuth 2.1 + Dynamic Client Registration
  • Plugin registry: https://github.com/osaurus-ai/osaurus-tools

Relay

  • Secure WebSocket tunnel via agent.osaurus.ai
  • Unique URL per agent based on crypto address
  • No port forwarding, no ngrok
05

Prompts

OSAURUS — Prompts

Prompt File Convention (from CLAUDE.md)

From the developer CLAUDE.md (AGENTS.md):

Prompt templates live in files, not Rust code: Multi-line prompt strings... go in 
crates/ironclaw_engine/prompts/*.md and are loaded via include_str!()

(Note: this is the ironclaw convention referenced in the shared CLAUDE.md; Osaurus follows analogous Swift patterns)

Verbatim: AGENTS.md Developer Guide Excerpt

## Keychain-Free Validation Gate

For Osaurus validation tied to vMLX, model runtime, parser/template, cache,
reasoning/tool, cancellation, or server-panel work:

- Do not run validation, build, signing, notarization, certificate, or
  `security` paths that trigger macOS Keychain or
  "wants to use your confidential information" prompts.
- Prefer source-only tests/audits and runtime probes that do not require
  signing or user authentication. If a prompt appears, stop the lane, 
  document the artifact as blocked, and switch to a keychain-free proof path.

## Model Runtime Non-Negotiables

- Never add forced thinking tags, parser repair, hidden sampler defaults,
  repetition-penalty rescues, close-token bias, or prompt/template coercion 
  to make a model appear coherent.
- Chat/API defaults must come from the active model bundle's 
  `generation_config.json` or equivalent runtime config unless a user 
  explicitly overrides them.
- Reasoning, tool, and chat-template behavior must be auto-detected from 
  the bundle/tokenizer/template/runtime config.

Technique: Strict behavioral non-negotiables for developer agents — a prohibitive constraint list preventing quality theater (faking model coherence, masking bugs). Unusual in its specificity about ML inference semantics.

Privacy Filter Behavior (from README)

Each detection is shown in a review sheet with a scrubbed preview before sending; 
approved entities are swapped for stable [PERSON_1] / [EMAIL_2] placeholders, and 
streaming replies are unscrubbed back on the fly so the chat reads naturally. 
Fail-closed: if the post-scrub scan finds anything that leaked, the send is blocked.

Technique: Automatic PII scrubbing with human review gate and fail-closed fallback — a security primitive in the prompt pipeline, not a conversational feature.

09

Uniqueness

OSAURUS — Uniqueness & Positioning

differs_from_seeds

OSAURUS has no close equivalent in the 11 seeds. It is philosophically similar to agent-os (personal harness, own your AI) but architecturally in a different class: native Swift vs bash scripts, Apple Container Linux VM sandbox vs in-place execution, MLX local inference vs API-only, secp256k1 identity vs no identity system, three-tier memory with salience scoring vs flat file memory. The closest technical parallel might be ccmemory (persistent memory + MCP server), but OSAURUS is a complete macOS application rather than a Claude Code plugin. Unlike any seed, OSAURUS incorporates an on-device LLM privacy filter (a 1.5B parameter model that scrubs PII before cloud sends).

Distinctive Positioning

  1. On-device privacy filter with fail-closed semantics: The openai/privacy-filter (1.5B sparse MoE) runs on-device, detects PII in pre-send text, shows a review sheet, substitutes placeholders, and blocks the send if post-scrub scan finds leakage. Wire-level Insights panel shows exactly what bytes the cloud received. Unique in this entire research corpus.

  2. Apple Container Linux VM with vsock bridge: True hypervisor-level isolation (Apple Silicon hardware-assisted) for code execution, not just process isolation. The vsock bridge is architecturally interesting — sandboxed but not disconnected.

  3. Cryptographic identity chain: secp256k1 addresses for every participant, authority chain from iCloud Keychain, revocable scoped access keys (osk-v1). This is identity infrastructure, not authentication.

  4. RAG-based automatic tool selection: Tools and skills selected automatically via RAG search — user configures capabilities but doesn't manually activate them.

  5. Plugin recipe system: "Extend with simple JSON plugin recipes, no Xcode or code signing required" — lowers barrier to writing sandbox extensions.

Observable Failure Modes

  • macOS only (Apple Silicon required) — no Linux/Windows support
  • Sandbox requires macOS 26+ (Tahoe) — not available to most users yet (2026-05-26)
  • Privacy filter model requires ~2.8 GB storage
  • MLX inference requires significant RAM/storage for larger models
  • The relay agent.osaurus.ai is a centralized dependency
  • Complex setup: Keychain, identity, provider OAuth flows
  • No git workflow automation — focused on chat/agent loop, not code commit pipelines
04

Workflow

OSAURUS — Workflow

Setup Phase

Step Artifact Gate
Install app (brew install --cask osaurus) Osaurus.app Automated
Launch, configure API keys Credentials in Keychain Manual
Create first agent Agent profile Manual (name, system prompt)
(Optional) Enable sandbox Apple Container VM macOS 26+ required
Connect cloud providers OAuth 2.1 flows Manual per provider

Per-Conversation Flow

Step Artifact
User starts chat in UI Conversation context
Working folder selected (optional) File tools enabled
Sandbox toggled (optional) Linux VM spawned
Memory retrieved (salience-based) ~800 tokens injected
Agent generates todo list, executes Markdown task list
Privacy filter screens before cloud send Scrubbed request
Response streamed, PII re-injected Natural text displayed
Session ends, memory distilled Episodes stored

Agent Loop (from docs/AGENT_LOOP.md)

"The model writes a markdown todo list, executes against it, and closes out with a verified summary — all in the same chat window."

Memory Consolidation

  • Background process: decays old facts, merges duplicates, evicts low-salience
  • Runs after session end, not per-turn
  • Maintains sharp memory instead of bloating

Self-Scheduled Agents

  • Agents can opt into a single self-scheduled next run
  • Stored in per-agent encrypted database
  • Enables autonomous monitoring workflows

Approval Gates

  • Privacy filter review sheet before cloud send (can approve or block)
  • Credentials scoped per agent (revocable access keys)
  • Sandbox requires explicit toggle per conversation
06

Memory Context

OSAURUS — Memory & Context

Memory Architecture (Three Tiers)

  1. Identity files — Personality, preferences, persistent agent characteristics
  2. Pinned facts — Explicitly remembered facts scored by user/agent
  3. Per-session episodes — Conversation history with transcript fallback

Salience Scoring

  • Each memory fact scored on relevance to current context
  • Background consolidator: decays, merges, evicts low-salience
  • Goal: sharp memory instead of bloating
  • Token budget: most turns inject ≤800 tokens; many inject zero

Session Distillation

  • Distillation happens ONCE at session end (not per turn)
  • Reduces context overhead during active conversation
  • Background consolidator runs asynchronously

Private Agent Database

  • Agents can opt into private encrypted per-agent database
  • Enables truly isolated memory per agent
  • Supports agent self-scheduling next run

Context Compaction

  • Salience-based retrieval naturally compacts context
  • RAG search for tool/skill selection (vs loading all)
  • "At most one compact slice per request based on what you're actually asking"

Cross-Session Handoff

  • Identity files provide session-to-session continuity
  • Pinned facts explicitly persist across restarts
  • Local storage means no cloud dependency for memory

Memory Isolation

  • Each agent has own memory by default
  • Cross-agent memory requires explicit configuration
  • VM agents connect to Osaurus memory via vsock bridge (not direct DB access)
07

Orchestration

OSAURUS — Orchestration

Multi-Agent

OSAURUS supports multiple named agents, each with own prompts, memory, tools, and visual theme. Agents run independently — no formal multi-agent coordination protocol.

Isolation Mechanism

Apple Container Linux VM (primary sandbox):

  • Powered by Apple's Containerization framework (requires macOS 26+/Tahoe)
  • Alpine Linux VM per agent
  • Each agent gets its own Linux user and home directory
  • /workspace mounted via VirtioFS
  • vsock bridge back to Osaurus host API
  • Zero risk to host Mac from sandbox execution

No container isolation without sandbox toggle — agents without sandbox enabled access host files directly.

Execution Mode

Interactive (primary): Chat-driven agent loop in UI Self-scheduled: Agents can schedule a single next run (autonomous monitoring) Relay-accessible: WebSocket tunnel makes agents reachable remotely

Multi-Model

Yes — model-agnostic design:

  • Local: MLX-based Apple Silicon inference (Gemma 4, Qwen3.6, etc.)
  • Apple Foundation Models (macOS 26+)
  • Liquid LFMs
  • Cloud: OpenAI, Anthropic, Gemini, xAI, Venice AI, OpenRouter, Ollama, LM Studio
  • Each agent can use a different model
  • Models swapped freely without losing agent/memory state

Orchestration Pattern

No formal orchestration pattern. Agents are independent. No worker/director hierarchy.

MCP Coordination

  • Osaurus IS an MCP server (osaurus mcp → stdio bridge)
  • Aggregates tools from ~25 remote MCP providers (OAuth 2.1)
  • Enables other MCP clients to access Osaurus agents' capabilities

Tool Selection

RAG-based automatic tool selection: "Tools and skills are automatically selected via RAG search based on the task at hand — no manual configuration needed."

08

Ui Cli Surface

OSAURUS — UI & CLI Surface

CLI Binary

  • osaurus binary
  • Subcommands:
    • osaurus ui — Open the chat UI
    • osaurus serve — Start the HTTP server
    • osaurus status — Check status
    • osaurus mcp — Start stdio MCP server

Desktop App (Primary UI)

  • Native SwiftUI macOS application
  • Download: .dmg from GitHub Releases or brew install --cask osaurus
  • Requires macOS 15.5+, Apple Silicon
  • Features:
    • Multi-agent chat UI
    • Agent management
    • Model browser / MLX model download
    • Memory visualization
    • Privacy filter Insights panel (shows bytes sent to cloud)
    • Remote MCP Providers management
    • Sandbox toggle per conversation
    • Identity / access key management
    • Relay URL display

Privacy Filter Insights Panel

  • Displays exact bytes transmitted to cloud models
  • Wire-level verification of PII scrubbing
  • Unique observability feature not found in other frameworks

Relay

  • Remote access via WebSocket tunnel to agent.osaurus.ai
  • Unique URL per agent (based on crypto address)
  • Enables mobile/remote access without port forwarding

IDE Integration

None. Osaurus is a standalone macOS app, not a VS Code extension or Claude Code plugin.

MCP Server

  • osaurus mcp starts an stdio MCP server
  • Any MCP-compatible client can connect to Osaurus tools
  • Enables integration with Claude Code, Cursor, etc. as an MCP provider

Observability

  • Privacy filter Insights panel (wire-level monitoring)
  • Agent status UI
  • Logs accessible via macOS Console or osaurus status

Related frameworks

same archetype · same primary tool · same memory type

Goose (Block/AAIF) ★ 46k
A12 UI passthrough

General-purpose AI agent (not just code) with security-first tool inspection, recipe-based shareable configurations, and 15+ LLM…

Vibe Kanban ★ 27k
A12 UI passthrough

Eliminate the overhead of planning, switching between agent terminals, and reviewing diffs by providing a single web dashboard…

1Code ★ 5.5k
A12 UI passthrough

Cursor-like desktop experience for Claude Code and Codex with cloud background agents, event-driven automations, and a full…

Crystal (stravu) ★ 3.1k
A12 UI passthrough

Manage multiple parallel AI coding sessions in isolated git worktrees from a single desktop GUI.

Maestro (RunMaestro) ★ 3.0k
A12 UI passthrough

Orchestrate unlimited parallel AI agent sessions with a keyboard-first desktop app including Group Chat coordination and Auto Run…

AgentsMesh ★ 2.1k
A12 UI passthrough

Multi-tenant workforce platform that gives every team member a squad of AI coding agents coordinated through channels, pod…