# Osaurus (official docs + repos)

Osaurus is a native Swift, MIT-licensed macOS AI harness for Apple Silicon: offline local MLX, Apple Foundation `foundation` on macOS 26+, optional cloud. This page is a source summary only — **Docs/repo-confirmed** vs **PR-only** (PR 2227).

Tags: source, osaurus, local-ai, macos, imessage, mcp

## Who / what

| Field | Value |
|---|---|
| Product | Osaurus — "the AI harness for macOS" (docs overview; README) |
| Org | Osaurus, Inc. (LICENSE copyright; README footer) · GitHub org [osaurus-ai](https://github.com/osaurus-ai) |
| Site | https://osaurus.ai/ |
| Docs | https://docs.osaurus.ai/ |
| App repo | https://github.com/osaurus-ai/osaurus (public; default branch `main`) |
| Messages plugin repo | https://github.com/osaurus-ai/osaurus-messages (public; default branch `master`) |
| License (app) | MIT — GitHub `license.key` = mit; LICENSE file: "Copyright (c) 2026 Osaurus, Inc." |
| License (plugin) | Not present. GitHub API `license` is null; contents listing has no LICENSE file |
| Language | Swift (both repos; GitHub API) |
| Latest release (API) | **0.23.0** (`published_at` 2026-08-18T22:35:13Z). Marketing site: "v0.23.0 · released 2 days ago" as of ingest |
| API snapshot (app, 2026-08-21) | 7668★ / 448 forks / 154 open issues / 32 subscribers; `created_at` 2025-08-17T15:05:39Z; `homepage` https://osaurus.ai |
| API snapshot (plugin, 2026-08-21) | 2★ / 2 forks / 2 open issues; `created_at` 2025-12-19T17:28:24Z; HEAD `70bd80c40fcf4f78fa051841b7fd23403cea7c38` |
| Requirements (docs + README) | macOS 15.5+ and Apple Silicon |
| Raw pack | raw/`web/osaurus-docs/` |

GitHub HTML for the app repo showed "0 forks" on ingest; API reported 448. Marketing homepage showed "0.0k downloads" and "0.0k stars" (JS placeholder). Counts above are the GitHub API snapshot, not live.

## Docs/repo-confirmed

Checked on ingest against the official pages and repo files listed under **Sources**. Quotes and lists below are from those pages. Features not on those pages are not stated here as confirmed.

### What it is

Docs overview + README: "Osaurus is the AI harness for macOS." Native Swift on Apple Silicon. "No Electron." MIT licensed. "Works fully offline with local models. Connect to any cloud provider when you want more power. Nothing leaves your Mac unless you choose."

Marketing site (https://osaurus.ai/): "Native Swift app for Apple Silicon." "Open the .dmg and launch — no account needed." "Apple Silicon. macOS 15.5+." Homebrew one-liner on that page: `brew install osaurus`. README install is `brew install --cask osaurus`, or the latest `.dmg` from GitHub Releases. App is "signed and notarized" (quickstart).

README footer: "Osaurus, Inc. · osaurus.ai".

### Requirements and macOS 26 features

Docs overview **System requirements**:

- macOS 15.5 or later
- Apple Silicon (M1, M2, M3, or newer)

Docs: "Apple Foundation Models require macOS 26 (Tahoe) or later, and the Sandbox uses its full Linux VM there — on macOS 15 the Sandbox falls back to a Seatbelt-confined backend." README: "The Linux VM requires macOS 26+ (Tahoe). On earlier versions Osaurus falls back to a native macOS Seatbelt sandbox."

### Models

Docs overview: local, Apple Foundation, or cloud. README **Local**: Gemma 4, Qwen3.6, GPT-OSS, Llama, and more via MLX; curated quants at Hugging Face `OsaurusAI`; models stored at `~/MLXModels` (override `OSU_MODELS_DIR`). README **Apple Foundation Models**: on macOS 26+, pass `model: "foundation"`; "Zero inference cost, fully private." Docs **Build with Osaurus**: "using `foundation` with zero setup on macOS 26+."

Quickstart Core Model picker: if `foundation` is available, "that's the right answer 99% of the time — it's free, fast, and never leaves your Mac." Table: macOS 26+ → `foundation`; macOS 15.5+ with a local model → smallest fast downloaded model (example `gemma-4-e2b-it-4bit`); cloud-only → any cheap fast remote (example `anthropic/claude-haiku-4-5`). "Choosing Use chat model (default) … leaves Core Model unset" and "memory won't update."

README **Cloud**: OpenAI, Anthropic, Gemini, xAI/Grok, Venice AI, OpenRouter, Ollama, LM Studio, or Osaurus Router.

### Overlay, agents, memory, skills

Docs overview:

- Overlay: press `⌘;` to talk; press again to dismiss.
- Agents: each with its own prompt, theme, and history.
- "Memory that learns from you. Past conversations are distilled into compact facts and surfaced only when relevant."
- "Skills that load themselves."

Quickstart: first-launch wizard names a "dino" (agent = saved configuration: system prompt, theme, default model, memory). Starter-plugin picker: "file access, shell, Calendar, Reminders, Messages. All optional" — add/remove later from Management → Plugins.

README Memory: three layers — identity, pinned facts, and per-session episodes — plus a transcript fallback. Distill once at session end. "Most turns inject ~800 tokens or less; many inject zero."

README Skills: import from GitHub repos or files, compatible with agentskills.io; Claude plugins can be imported as a bundle; Methods are learned workflows. Selected via RAG.

### Trusted folders vs Sandbox (mutually exclusive)

Docs overview **Trusted folders**: "Point a chat at a folder and the agent gets safe file, search, and git tools — scoped to just that directory."

Docs overview **Sandbox**: "Toggle it on and the agent can run shell, Python, and Node in isolation — a Linux VM on macOS 26+, a Seatbelt-confined runner on macOS 15. Trusted-folder and Sandbox modes are mutually exclusive: selecting a folder disables Sandbox, while enabling Sandbox clears folder selections from visible chats using that agent."

README Agent Loop: "Pick a working folder and the agent gets file, search, and git tools. Toggle the sandbox and it gets shell access in an isolated sandbox."

### Computer Use / Browser Use (experimental + gated)

Docs overview: "Computer Use (experimental). Let an agent drive real macOS apps … with every action gated by a safe-by-default confirmation policy." "Browser Use. Give an agent its own persistent, isolated browser … with the same safe-by-default action gating."

docs.osaurus.ai/computer-use: "It is off by default, enabled per agent (custom agents only — the built-in Default agent can't use it), and every action passes through a safe-by-default autonomy gate before it runs." Callout: "Computer Use is an experimental feature." Default autonomy preset `balanced` "confirms every edit and consequential action." Tool name: `computer_use`. Requires Accessibility; Screen Recording optional for screenshot perception.

README Browser Use: `browser_use` subagent; persistent per-agent WebKit session; "Off by default, enabled per agent."

### Schedules / watchers

Docs overview: "Schedules and Watchers. Run an agent on a timer, or whenever a folder changes." README Automation: "Schedules run recurring tasks in the background. Watchers monitor folders and trigger agents on file changes."

### MCP in and out

Docs overview: "it's a full MCP server and client." README: `osaurus mcp` is a stdio MCP server that proxies to the local HTTP server. As a client, Osaurus aggregates URL-based remote MCP providers (HTTP/SSE). "It does not launch third-party `command`/`args` stdio providers."

Local MCP HTTP (docs API + architecture): `GET /mcp/health`, `GET /mcp/tools`, `POST /mcp/call` on the same port as chat APIs.

### Local APIs

Docs API + README: base URL `http://127.0.0.1:1337` (override with `OSU_PORT`). Compatible APIs at the same port: OpenAI, Anthropic, Open Responses, Ollama.

| API | Endpoint (docs API table) |
|---|---|
| OpenAI | http://127.0.0.1:1337/v1/chat/completions |
| Anthropic | http://127.0.0.1:1337/v1/messages |
| Ollama | http://127.0.0.1:1337/api/chat |

Docs API: "The router normalizes `/v1`, `/api`, and `/v1/api` prefixes before dispatch." Loopback accepts requests without auth; non-loopback needs an `osk-v1` access key.

**Conflict (cite both):** README Compatible APIs table lists Anthropic as `http://127.0.0.1:1337/anthropic/v1/messages`. Docs API: "Upstream overview copy calls `/anthropic/v1/messages` canonical, but the pinned server handler registers `/messages` and its normalized `/v1/messages` alias. … this guide does not claim the `/anthropic`-prefixed path is an alias."

### POST /memory/ingest (generic chat-log seed)

Docs API **Memory API**: `POST /memory/ingest` — "Bulk-ingest conversation turns so the memory system can learn from them. Useful for seeding memory from existing chat logs, migrating from another system, or running benchmarks." Required body fields: `agent_id`, `conversation_id`, `turns` (each turn has `user` and `assistant` strings). Optional: `session_date`, `skip_extraction`. Response: `{"status":"ok","turns_ingested":N}`.

This is a generic memory endpoint. The fetched API page does not mention iMessage, Messages.app, or chat.db.

Related on the same page: `GET /agents` (custom agents + `memory_entry_count`); `X-Osaurus-Agent-Id` on `POST /v1/chat/completions` attributes the session but "agent memory is not injected into the prompt on this path."

### Starter plugin: Messages (osaurus-messages)

Quickstart names **Messages** among optional starter plugins.

osaurus-messages README (master): "An Osaurus plugin for interacting with macOS Messages.app. Send and read iMessages programmatically."

| Tool | What the README says |
|---|---|
| `send_message` | Send to a phone number. "Tries iMessage first and automatically falls back to SMS (requires Text Message Forwarding) when iMessage is unavailable." "Uses AppleScript to interact with Messages.app directly" (`NSAppleScript`). Params: `phoneNumber`, `message`. Requires Automation → Messages. |
| `read_messages` | History for one contact. "Queries the Messages database directly using the native SQLite C API." Params: `phoneNumber`, optional `limit` (default 10, max 50). |
| `get_unread_messages` | Unread from all contacts. Same SQLite path. Optional `limit` (default 10, max 50). |
| `search_messages` | Case-insensitive substring search. Read-only SQLite. Optional `phoneNumber`; `limit` default 20, max 50. Does not full-text search text that lives only in the `attributedBody` blob. |
| `list_conversations` | Recent direct and group chats with unread counts. Read-only. `limit` default 15, max 50. |
| `detect_spam` | Heuristic pre-filter on recent received messages. "never deletes anything." |

Architecture (README): send via AppleScript; read via native SQLite C API (`import SQLite3`) against `~/Library/Messages/chat.db` **in read-only mode**. "All queries use parameterized bindings." Full Disk Access required to read that database.

Package.swift (master): package name `osaurus-messages`; `.macOS(.v13)`; depends on `osaurus-ai/osaurus-plugin-sdk` exact `1.0.0`. Publishing example in README: `osaurus tools package osaurus.messages 0.1.0`.

This plugin is a tool plugin (read/send). It is not described in the fetched plugin README as the native Agent Channel.

### Global proxy vs iMessage channel (docs)

docs.osaurus.ai/global-proxy: the global proxy covers remote provider HTTP, remote MCP, model downloads, "Slack, Discord, and Telegram API requests, plus custom JSON Agent Channel HTTP requests," plugin HTTP, etc. "Local loopback health checks deliberately stay direct." Then: **"iMessage channel traffic is local to Messages.app and its helper, so it has no remote HTTP session to proxy."**

That sentence is the official-docs confirmation that an iMessage channel exists and that it is local to Messages.app + helper. Mechanism details are not on that page.

### Other docs/repo facts (not expanded)

- Voice: on-device (docs: Apple Neural Engine; README: FluidAudio).
- Image generation: local image models, offline (docs + README).
- Public links: tunnel through `agent.osaurus.ai` (docs + README Relay).
- Privacy Filter: experimental on-device classifier for cloud prompts (docs overview; README names `openai/privacy-filter`).
- Telemetry conflict (cite both): marketing site "Private" card: "Nothing leaves your Mac. No telemetry, no training on your data, no servers in the loop." README + quickstart: anonymous Aptabase usage analytics (welcome-screen opt-in); Sentry crash reporting is a separate switch, "opt-out — on by default."
- Plugin ABI conflict (cite both): docs tools: host API "v1 through v6." README architecture diagram: "Plugin System (v1 / v2 ABI)." README Tools: "Plugins target the v3 host API surface" and "Older v1/v2 plugins continue to load unchanged."

## PR-only

The following is from [osaurus-ai/osaurus#2227](https://github.com/osaurus-ai/osaurus/pull/2227) only (GitHub pull HTML on ingest). Not restated as current product docs. The PR is **merged** and labeled **released**.

| Field | PR page |
|---|---|
| Title | Add native iMessage agent channel with download-only imsg helper |
| State | merged |
| Author | tpae |
| Created | 2026-07-29T22:47:15Z |
| Merged | 2026-07-29T23:26:11Z |
| Merge commit | `0bbb9f7e1b4f524680c14c962d269bc23732d7f9` |
| Diff | +11950 / −79 in 46 files |
| Labels | enhancement, released |

PR summary (paraphrase of the PR body, not docs):

- Adds iMessage as a **native Agent Channel** on macOS, driven by a pinned, digest-verified [imsg](https://github.com/openclaw/imsg) helper (PR: v0.13.4, MIT) speaking newline-framed JSON-RPC.
- Helper is **download-only** — acquired on demand from iMessage settings (PR compares this to sandbox runtime and models). App build/signing/notarization "completely untouched"; pin file named: `scripts/build/imsg-helper-manifest.json`.
- Receive: live `watch.subscribe` stream with a persisted `chat.db` ROWID cursor; since-rowid backfill after helper restarts; GUID dedupe; timeout-triggered kill of a wedged helper.
- Helper trust: SHA-256 pins, per-spawn bridge dylib re-verification, Mach-O architecture validation; quarantine stripped only after digests match.
- Agent Channels parity named in the PR: manifest gate, action policies (advanced private-API actions gated), tapback normalization, self-message policy, Activity scope, auto-destinations.
- Guided setup UI, diagnostics, send-only support, duplicate-instance guidance, localization (de/ko/ru/zh-Hans/zh-Hant).
- "Advanced (private-API) actions require operator-disabled SIP/Library Validation, which Osaurus only diagnoses — never changes." Security/pin-rotation doc named: `docs/CHANNEL_RELEASE_RUNBOOK_IMESSAGE.md` (file not fetched this ingest).
- Test-plan live smoke (PR checklist, not a docs page): "download helper from iMessage settings, grant Full Disk Access + Messages Automation, verify allowlisted receive + confirmed send."

`api.github.com/repos/osaurus-ai/osaurus/pulls/2227` timed out on ingest; no extra API fields.

## Overlap / gaps (sources vs each other, not advice)

- Official docs (global-proxy) confirm an **iMessage channel** that is local to Messages.app + helper. PR 2227 is the page that names the helper as pinned **imsg**, `watch.subscribe`, the `chat.db` ROWID cursor, download-only install, and the FDA + Messages Automation smoke steps.
- **osaurus-messages** (repo) is a plugin: `send_message` via AppleScript; `read_messages` / `get_unread_messages` (plus search/list/spam tools) via read-only SQLite on `~/Library/Messages/chat.db`. Quickstart lists Messages as a starter plugin. That is a different surface from the PR's native Agent Channel.
- `POST /memory/ingest` is a generic memory-seed API (docs API). It is not iMessage-specific on the fetched page.
- Slack / Discord / Telegram Agent Channel traffic is remote HTTP and is covered by the global proxy (docs). iMessage is called out as the exception (local, not proxied).
- Anthropic base path: README `/anthropic/v1/messages` vs API docs registered `/v1/messages` — both cited above.
- Telemetry: marketing "No telemetry" vs README/quickstart Aptabase + default-on Sentry — both cited above.

## Sources

1. https://docs.osaurus.ai/
2. https://docs.osaurus.ai/quickstart
3. https://docs.osaurus.ai/global-proxy
4. https://docs.osaurus.ai/api
5. https://docs.osaurus.ai/tools
6. https://docs.osaurus.ai/computer-use
7. https://osaurus.ai/
8. https://github.com/osaurus-ai/osaurus
9. https://raw.githubusercontent.com/osaurus-ai/osaurus/main/README.md
10. https://github.com/osaurus-ai/osaurus/blob/main/LICENSE
11. GitHub API: `https://api.github.com/repos/osaurus-ai/osaurus` and `.../releases/latest` (0.23.0)
12. https://github.com/osaurus-ai/osaurus-messages
13. https://raw.githubusercontent.com/osaurus-ai/osaurus-messages/master/README.md
14. https://raw.githubusercontent.com/osaurus-ai/osaurus-messages/master/Package.swift
15. GitHub API: `https://api.github.com/repos/osaurus-ai/osaurus-messages` (+ contents, commits?per_page=1)
16. https://github.com/osaurus-ai/osaurus/pull/2227 (PR-only section)
17. Raw ingest: `raw/web/osaurus-docs/` (`source.url`, `notes.md`, `metadata.json`)

## Related pages

- [[hermes-agent]] (other MIT self-hosted agent runtime; different OS/stack)
- [[grok-bot]] (managed cloud teammates; not local macOS)
- [[ia-local-casa]] (local home RAG stack)
- [[docker-mcp-toolkit-homelab]] (MCP catalog/gateway; Osaurus is also MCP server+client)
- [[macro]] (workspace with hosted MCP; not a local macOS harness)
- [[youtube-local-router-nemotron-lightning]] (local routing; not Osaurus)