Configuration & Server Settings
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."
agents:
- name: Research Agent
system_prompt: "Research thoroughly and cite sources."
temperature: 0.4
capabilities:
tools_enabled: true
web_search_enabled: true
delegation:
local_text_enabled: true
spawnable_agents: ["Research Agent"]
spawn_tool_access: read_only
permission_defaults:
spawn: ask
Documents can manage memory, default_agent, active_agent, custom agents, tools, delegation, slash commands, knowledge_collections, channels, mcp_servers, local models, native plugins, cloud providers, search_providers, schedules, and watchers.
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, 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 in its Capabilities settings. 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
Management → Chat → 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, Osaurus asks you to choose a model the first time compaction runs rather than silently using the active chat model. Chat compaction →
Memory
Memory is on by default, with ten settings. Edit them in Management → 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
Management → Server → Settings → Model Memory:
| Setting | Description |
|---|---|
| Eviction policy | Strict (One Model) keeps one model loaded (default); Flexible (Multi Model) allows concurrent models for high-RAM systems |
| Keep model loaded after use | Idle residency after the last request — 5/15/30/60 minutes (default 15), Immediately, or Never |
| Sampling Defaults | Optional temperature, top-p, top-k, min-p, repetition penalty, and max-token defaults. Blank fields defer to the model bundle. |
| Disk Cache Size (% of disk) | Blank uses 10% of the cache volume; the shared cap is further limited at model load to 25% of currently free disk |
| Clear SSD Cache | Safely remove reusable KV checkpoints and reclaim the cache volume |
| Allowed origins | CORS origins (currently *) |
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 subagent batches. The same value appears in Main Chat Spawn and every agent's Max subagents per batch control; editing either surface updates the canonical limit.
Leave the field empty for Automatic, which resolves a safe value from the active Memory Safety profile. Values are clamped to 1–32. RAM admission, current engine occupancy, and local-model residency can still split a subagent batch into smaller waves.
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 Management → 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 Management → Privacy → Storage if your threat model calls for it — the same panel handles backups, key rotation, and recovery. 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 Identity → 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