Configuration
Osaurus works out of the box with sensible defaults. This page covers the knobs you can turn.
Declarative configuration
Describe the parts of Osaurus you want to manage in one versioned YAML or JSON document. The planner compares that desired state with the running app, validates the whole document, and shows the exact changes and risks before the applier writes anything.
The same engine powers:
- the Orchestrator's
osaurus_configtool andosaurus_inspectread surface; osaurus config export|schema|plan|apply; and- loopback-only
/admin/config/*HTTP endpoints.
Example
version: 1
memory:
enabled: true
budget_tokens: 1200
default_agent:
name: Osaurus
model: foundation
system_prompt: "Be concise and delegate specialist work."
new_chat_agent: default
agents:
- name: Research Agent
description: "Web research with cited sources"
system_prompt: "Research thoroughly and cite sources."
model: null # inherits the Orchestrator's model
temperature: 0.4
capabilities:
tools_enabled: true
web_search_enabled: true
apple_apps: [calendar, reminders]
delegation:
local_text_enabled: true
spawnable_agents: ["Research Agent"]
spawnable_workspace_agents: [] # teammates' shared agents as Name@Workspace
permission_defaults:
spawn: always_allow
spawn_workspace: ask
budget_max_tokens: 8192
budget_max_turns: 24
budget_max_seconds: 900
Documents can manage memory, default_agent, new_chat_agent, custom agents, tools, delegation, slash commands, knowledge_collections, channels, mcp_servers, local models, native plugins, cloud providers, search_providers, schedules, and watchers.
A few sections worth knowing:
| Key | What it covers |
|---|---|
new_chat_agent | The agent new chats open with: default (the Orchestrator) or a custom agent's name. The older active_agent name is still accepted. |
agents[].model | null inherits the Orchestrator's model |
agents[].capabilities | Ability switches, including image_enabled, applescript_enabled, browser_use_enabled, computer_use_enabled, and apple_apps — a list from calendar, reminders, contacts, notes, mail, messages, maps, music, shortcuts that replaces the agent's set |
delegation | The Orchestrator's allowed subagents (spawnable_agents, spawnable_workspace_agents), workspace_auto_join (set a workspace to false to stop its shared agents joining automatically), permission_defaults (spawn, spawn_workspace: ask / deny / always_allow), worker limits (budget_max_tokens, budget_max_turns, budget_max_seconds), and the local-model memory settings (local_text_enabled, ram_safety_preflight) |
Working folders and the per-agent model override aren't part of the document; set them in the app. Apple Apps → · Subagents →
Semantics and safety
- Merge by default. Missing keys stay untouched; explicit
nullclears an optional override. - Entities match by name, case-insensitively. Listed agents, providers, MCP servers, schedules, and watchers are created or patched.
- Plan is read-only. Only
applymutates state. - Prune is an explicit argument, not a document key. It deletes unlisted entries only in sections present in the document and refuses broken cross-references.
- Validation is all-or-nothing. Unknown keys, bad values, and invalid references stop the whole document before changes begin.
- High-risk changes need an extra confirmation. Examples include prune deletions, browser or Computer Use grants, relay exposure, channel writes, new or stdio MCP endpoints, automatic tool policies, and looser delegation permissions.
- Documents are capped at 512 KiB.
Secrets
Exports never include secrets or reveal whether a credential exists. Documents accept references, not raw keys:
env:VARIABLE_NAMEkeychain:SERVICE/ACCOUNTset_api_key: trueto open the native credential sheet during apply
Provider api_key_ref, MCP token_ref/secret_env_refs, and channel bot_token_ref resolve only at apply time. OAuth, device pairing, macOS permission grants (including the Apple app permission prompts), folder pickers, destructive resets, payment, server runtime, app appearance, voice, sandbox resources, privacy filtering, and image targets remain interactive Settings work by design.
CLI workflow
osaurus config export -o osaurus-config.yaml
osaurus config schema
osaurus config plan osaurus-config.yaml
osaurus config apply osaurus-config.yaml
# Destructive or otherwise high-risk changes
osaurus config plan osaurus-config.yaml --prune
osaurus config apply osaurus-config.yaml --prune --yes
apply exits 0 when fully converged, 1 when a change fails or is cancelled, and 3 when changes applied but an interactive step such as credential entry remains.
Orchestrator → · CLI reference → · HTTP endpoints →
Environment variables
| Variable | Description | Default |
|---|---|---|
OSU_PORT | Server port number | 1337 |
OSU_MODELS_DIR | Custom MLX models directory | ~/MLXModels |
# Persistent (shell profile)
export OSU_PORT=8080
export OSU_MODELS_DIR=/Volumes/External/MLXModels
# Or inline
OSU_PORT=8080 osaurus serve
Server flags
osaurus serve accepts:
| Option | Description | Default |
|---|---|---|
--port, -p | Server port | 1337 |
--expose | Bind to all interfaces (LAN access) | localhost only |
osaurus serve # localhost:1337
osaurus serve --port 8080 # localhost:8080
osaurus serve --expose # 0.0.0.0:1337 (LAN)
osaurus serve --expose --port 1337 # 0.0.0.0:1337 (LAN, explicit)
When you --expose, anyone on your network can reach your Osaurus. Use access keys to protect endpoints — see Identity.
Capabilities (auto-selection)
Each agent has a tool mode under Abilities → Tools. In Auto mode (the default), the model starts with a small always-loaded set and pulls in more of your enabled tools, skills, and methods on demand via capabilities_discover / capabilities_load. In Manual mode, all enabled capabilities are sent every turn at the cost of larger system prompts. Skills → · Methods →
Chat
Settings… (⌘ ,) → Conversation → Advanced → Compaction Model selects the model used to summarize older messages when a conversation approaches its context limit. Local, Foundation, and remote models are supported; remote compaction requests honor your Privacy Filter settings. If unset, the chat's current model summarizes. To lower every model's chat context window, use Server → Settings → Cache → Context Window Cap. Chat compaction →
Memory
Memory is on by default, with ten settings. Edit them in Settings… → Memory or in ~/.osaurus/config/memory.json:
| Setting | Default | Description |
|---|---|---|
enabled | true | Master toggle |
embeddingBackend | mlx | Embedding backend (mlx / none) |
embeddingModel | nomic-embed-text-v1.5 | Embedding model used by VecturaKit |
extractionMode | sessionEnd | When to distill (sessionEnd / manual) |
relevanceGateMode | heuristic | Read-path gate (off / heuristic / llm) |
memoryBudgetTokens | 800 | Per-request budget (100–4,000) |
summaryDebounceSeconds | 60 | Inactivity before distillation (10–3,600) |
consolidationIntervalHours | 24 | Background consolidator cadence (1–168) |
salienceFloor | 0.2 | Eviction threshold for pinned facts (0–1) |
episodeRetentionDays | 365 | Episode/transcript retention (0 = forever) |
Local inference
Settings… → Server → Settings:
| Section | Setting | Description |
|---|---|---|
| Model Memory | Eviction Policy | Strict (One Model) keeps one model loaded (default); Flexible (Multi Model) allows concurrent models for high-RAM systems |
| Model Memory | Keep Model Loaded / Unload After | Off by default: a model unloads 30 seconds after its last request (or when the last chat window using it closes). Pick 5, 15, or 30 minutes, 1 hour, or Immediately instead — or turn on Keep Model Loaded to never unload. |
| Sampling Defaults | Optional temperature, top-p, top-k, min-p, repetition penalty, and max-token defaults. Blank fields defer to the model bundle. | |
| Cache | Disk Cache Size (% of disk) | Blank is Automatic: 30% of free space plus the cache's own bytes. An explicit percentage uses total disk size, bounded by 25% of free space plus the cache. |
| Cache | Clear SSD Cache | Safely remove reusable KV checkpoints and reclaim the cache volume |
| Cache | Context Window Cap | Lower every model's chat context window |
| Connection | Allowed Origins (CORS) | For browser apps only; loopback is always allowed. * allows any origin, otherwise a comma-separated list. |
Sampler precedence is request/agent → your Sampling Defaults → model bundle → engine. Live Activity → Sampler last used reports what actually ran. Inference Runtime details →
Concurrency & Batching
Server → Settings → Concurrency & Batching → Concurrent Sessions is the shared concurrency limit for same-model requests and local subagents. The same value appears as Max local subagents at once in Settings → Orchestrator and every agent's Subagents tab; editing either surface updates the shared limit.
Leave the field empty for Automatic, which resolves a safe value from the active Memory Safety profile. Values are clamped to 1–32. Memory checks, current engine occupancy, and local-model residency can still split a wave of subagents into smaller groups.
With Continuous Batching off (the default), each local model is pinned to one active job even when Concurrent Sessions is higher. Turning it on allows same-model requests to decode together. A limit of 1 keeps vmlx's compiled-decode fast path; higher limits trade that speedup and additional wired memory for throughput. Remote jobs can still overlap when local continuous batching is off.
The legacy defaults knob still works when no runtime setting is present:
defaults write ai.osaurus ai.osaurus.scheduler.mlxBatchEngineMaxBatchSize -int 8
The legacy value is clamped to [1, 32]; the Server setting takes precedence. Inference Runtime details →
Sandbox
The sandbox is configured in Settings… → Sandbox → Container → Resources or by editing ~/.osaurus/config/sandbox.json (the Linux VM backend on macOS 26+; macOS 15 uses the Seatbelt fallback, which has no VM resources to configure):
{
"autoStart": true,
"cpus": 2,
"memoryGB": 2,
"network": "outbound"
}
| Setting | Range | Default |
|---|---|---|
autoStart | true / false | true |
cpus | 1–8 | 2 |
memoryGB | 1–8 | 2 |
network | outbound / proxy / none | outbound |
proxy boots the VM on a host-only network with a domain-allowlist egress proxy; it's selected automatically when the provisioning agent has Allowed Domains configured. Changes require a container restart. Sandbox Internals →
Storage encryption
Local data is plaintext SQLite by default, protected at rest by FileVault. Turn on whole-database SQLCipher encryption in Settings… → General → Advanced → Data & Storage if your threat model calls for it — the same panel handles backups, key rotation, recovery, and how long file-change history is kept. Storage & Encryption →
API path prefixes
Endpoints are available under multiple prefixes for compatibility:
/v1/endpoint— OpenAI style/api/endpoint— generic / Ollama style/v1/api/endpoint— combined
All prefixes route to the same handlers.
HTTP server limits
To prevent unauthenticated clients from exhausting host memory, Osaurus rejects oversized request bodies before the auth gate:
| Endpoint | Limit |
|---|---|
POST /pair | 64 KiB |
| Other public HTTP routes | 32 MiB |
| Sandbox host bridge | 8 MiB |
Oversized requests return 413 Payload Too Large.
Where things live
| What | Path | Override |
|---|---|---|
| MLX models | ~/MLXModels/ | OSU_MODELS_DIR |
| App data root | ~/.osaurus/ | not configurable |
| Plugin install root | ~/.osaurus/Tools/<plugin_id>/<version>/ | not configurable |
| Voice models | ~/Library/Application Support/FluidAudio/Models/ | not configurable |
| Memory | ~/.osaurus/memory/memory.sqlite + vectura/{agent}/ | not configurable |
| Chat history | ~/.osaurus/chat-history/history.sqlite + blobs/ | not configurable |
| Methods | ~/.osaurus/methods/methods.sqlite | not configurable |
| Tool index | ~/.osaurus/tool-index/tool_index.sqlite | not configurable |
| Schedules | ~/.osaurus/schedules/{uuid}.json | not configurable |
| Watchers | ~/.osaurus/watchers/{uuid}.json | not configurable |
| Skills | ~/.osaurus/skills/{name}/SKILL.md | not configurable |
| Themes | ~/.osaurus/themes/{uuid}.json | not configurable |
| Sandbox plugins | ~/.osaurus/sandbox-plugins/ | not configurable |
| Sandbox container | ~/.osaurus/container/ | not configurable |
| Configs | ~/.osaurus/config/*.json | edit directly |
| Encryption key (opt-in encryption only) | macOS Keychain (com.osaurus.storage) | see Storage |
| Identity master key | iCloud Keychain | see Identity |
Per-request configuration
Most generation behavior is per-request via API parameters:
{
"model": "gemma-4-e2b-it-4bit",
"messages": [{ "role": "user", "content": "Hello" }],
"temperature": 0.7,
"max_tokens": 1000,
"top_p": 0.9,
"stream": true,
"session_id": "my-conversation"
}
Recommended setups
Single-machine local-first development:
osaurus serve # default port, loopback only
LAN access for testing on phone or another laptop:
osaurus serve --expose
# Then mint an osk-v1 access key from Settings… → Server → Overview → Access Keys
External drive for large models:
export OSU_MODELS_DIR=/Volumes/ModelsDrive/MLXModels
osaurus serve
Multiple instances (one per project, etc.):
# Terminal 1
OSU_PORT=1337 osaurus serve
# Terminal 2 (separate models dir if you want isolation)
OSU_MODELS_DIR=~/MLXModels-experimental OSU_PORT=1338 osaurus serve
Related:
- Storage & Encryption — SQLCipher migration, key rotation, plaintext export
- Memory Internals — settings explained
- Inference Runtime — what the batch-size knob actually does
- Identity —
osk-v1keys, whitelists, revocation