osaurus-ai/osaurus

1. Top-level shape

- This is a macOS-native Swift system with one app target (App/osaurus), one command-line entrypoint (Packages/OsaurusCLI), and a large shared core library (Packages/OsaurusCore). Most runtime behavior lives in the core package and is reused by both the GUI and CLI.

2. User-facing entry points

- The macOS app is the primary interactive shell: SwiftUI views, app intents, management panels, and system-wide integrations.

- The CLI exposes operational commands like serve, ui, status, mcp, and tools ...; it is the operational gateway for headless/server use and for external harnesses.

3. Core runtime boundary

- OsaurusCore is the main architecture boundary. It contains models, services, managers, storage, networking, tools, identity, sandbox, memory, privacy filtering, and views.

- The codebase is organized so “services” hold business logic, “managers” hold UI-facing state, and “views” render feature surfaces on top of them.

4. Conversation and agent loop

- Chat is the central orchestration flow. A session collects user messages, attachments, tool results, memory, and model responses.

- The agent loop composes prompts, selects tools, streams model output, handles tool calls, and persists the resulting transcript/state. This loop is reused across the UI, server API, and evaluation harnesses.

5. Model/inference subsystem

- Model access is abstracted behind ModelService / Inference services and supports several backends: local MLX, Apple Foundation Models, and remote providers such as OpenAI-compatible, Anthropic, Gemini, xAI/OpenRouter/Ollama-like endpoints.

- The model layer is not just transport: it also handles model selection, runtime policy, token budgeting, batching, residency/lease management, and capability-specific routing.

6. Tooling and plugin system

- Tools are a first-class layer beneath the agent loop. Core tool types include built-ins, folder tools, sandbox tools, database tools, capability tools, and MCP/provider-backed tools.

- There is a plugin ABI plus a repository/install layer (OsaurusRepository) for native plugins and Claude-style plugin bundles. The tool registry decides exposure, permissions, and routing into these capabilities.

7. Sandbox execution boundary

- The sandbox is a hard trust boundary: agents can run code in an isolated Linux VM managed by Apple Containerization, with host/guest communication via vsock and shared workspace mounts.

- Host-side sandbox services provision the VM, register tools, stream logs, enforce security policies, and mediate file/artifact access. This is where “real code execution” is kept separate from the macOS host.

8. Identity and secure communication

- Identity is cryptographic and per-participant: master keys, agent keys, pairing keys, revocation, and secure session stores live in Identity.

- This supports local access keys, pairings, and secure channel connections. The secure-channel layer encrypts agent-to-agent or relay-mediated traffic end to end, while the relay itself stays blind to plaintext.

9. Networking and server surfaces

- Networking contains the local HTTP server, request parsing/validation, OpenAI/Anthropic/Ollama-compatible endpoints, MCP endpoints, relay tunneling, Bonjour discovery, and auth gates.

- The same server layer powers local API consumption, remote exposure, and the stdio MCP bridge used by external MCP clients.

10. Storage and persistence

- State is persisted through multiple SQLite-backed stores: chat history, agents, tools, plugins, schedules, memory, billing/credits, and server/runtime settings.

- There is also encrypted storage for secrets and sensitive per-agent data. Storage is a shared persistence layer underneath chat, identity, memory, plugins, and tooling.

11. Memory and privacy

- Memory is a distinct subsystem with embeddings, search, consolidation, relevance gating, and per-session context assembly.

- Privacy filtering sits on the outbound path to cloud models: content is redacted, reviewed, then streamed back with placeholders unscrubbed for display. The design is fail-closed, so leakage blocks send.

12. Knowledge and reuse layers

- Skills, methods, slash commands, watchers, schedules, themes, and document adapters are all separate feature layers that feed into the agent experience.

- These are discovered and selected through search/routing services rather than manual wiring, which means the agent can dynamically pick relevant capability bundles.

13. Document and attachment pipeline

- File attachments are not treated as plain blobs when structure matters. Dedicated adapters parse CSV, XLSX, PPTX, PDF, and rich documents into structured representations before they reach the model.

- This keeps the agent’s context higher-fidelity and lets tools operate on structured content instead of only raw text.

14. Observability, quality, and release plumbing

- Telemetry and crash reporting are optional, privacy-conscious, and separated from product data. The repo also contains extensive test suites, eval harnesses, live-proof scripts, benchmark scripts, and CI/release workflows.

- These don’t drive runtime behavior, but they strongly shape the architecture by enforcing stability across inference, sandboxing, privacy, plugin ABI, and provider compatibility.