Agents
One AI doesn't fit every job. When you're writing code you want a focused technical assistant. When you're brainstorming you want creativity. When you're researching you want web access. Agents let you save those configurations and switch between them with a click.
What an agent is
An agent is a saved configuration with its own:
- Identity — name, description, optional avatar (mascot or initial monogram), and a cryptographic address derived from your master key
- Personality — system prompt, optional default model, optional generation overrides (temperature, max tokens), optional theme that activates when the agent is selected
- Abilities — every capability switch in one place: tools, memory, knowledge, web search, charts, speech, self-scheduling, database, code execution, and host files — with a live estimate of what each one costs in startup context
- Tools — its own enabled set of tools, plus an Auto vs Manual toggle (more below). Skills aren't scoped per agent — they come from the universal Skills library.
- Memory — pinned facts, episode digests, and identity overrides are stored per-agent
- Database — an optional private, encrypted SQLite database for structured data across runs (see Agent DB)
- Sandbox permissions — an
autonomous_execconfig that controls exactly what the agent may do in the Sandbox, down to per-domain network allowlists - Subagents — per-agent delegation settings: spawnable agents/models, the
imagetool, Computer Use, Browser Use, and AppleScript, all off by default (see Subagents) - Automation — per-agent schedules and file watchers, plus opt-in self-scheduling
- Quick actions — per-agent prompt templates shown in the chat empty state, separate lists for Chat and Work modes
- Plugin instructions — optional per-plugin instruction overrides
- Bonjour discovery — opt-in flag that advertises the agent on your local network so connector apps can find it
You can override almost everything per-agent, or leave fields empty to fall back to your global defaults.
Creating an agent
- Open the Management window (
⌘ ⇧ M) → Agents - Click Create Agent
The Create Agent sheet is deliberately short — pick from Start From starter templates (or begin blank), then:
- Name — required (e.g. "Code Assistant"); templates prefill a sensible one
- Avatar — pick a mascot icon, or leave it blank for an initial-monogram badge in the agent's auto-assigned color
- Model (optional) — locks this agent to a specific model regardless of your global pick
- Capabilities — starts with everything enabled; click Customize… for the full tool picker in draft mode (nothing persists until you create)
- Prompt — the system prompt prepended to every message in chats with this agent
Click Create Agent and it's immediately available in the agent selector. Everything else — generation overrides, theme, quick actions, sandbox permissions, automation — lives in the agent's detail view, described next.
Example system prompts
Code Assistant (low temperature, focus on correctness):
You are an expert software engineer. You write clean, efficient,
well-tested code. You consider edge cases, suggest improvements
when relevant, and admit when you don't know something.
Creative Writer (high temperature, vivid output):
You are a creative writing assistant with a flair for vivid
descriptions and engaging narratives. You help craft compelling
stories, poems, and creative content with an expressive style.
Research Helper (balanced temperature, structured output):
You are a research analyst. For every question, you cite sources,
flag uncertainty, and structure findings into:
- Executive summary
- Key findings
- Confidence assessment
The agent detail view
Open any custom agent to get its detail view: five plain-language groups in the sidebar, each holding a few focused tabs.
| Group | Tabs | What's there |
|---|---|---|
| General | Configure · Appearance | Identity, system prompt, model, generation overrides, per-agent voice, self-scheduling limits · avatar, empty-state quick actions, visual theme |
| Abilities | Overview · Tools · Subagents · Sandbox | Every capability switch with a live context estimate · the tool picker · delegation settings · sandbox permissions and secrets. Installed agent plugins get their own tabs in this group too. |
| Connections | Network · Remote Connections | Bonjour discovery and the relay tunnel · every peer granted access to this agent, with usage and a Revoke action |
| Automation | Automation | Per-agent schedules and file watchers |
| Memory | Memory · Database | Chat history, pinned facts, episodes · the agent's Database workspace |
Abilities
Abilities → Overview is the one place to see and flip everything a custom agent can do. A hero card shows how many abilities are on and a live estimated startup context — the number responds to every toggle (with a +/- tokens delta), priced through the same gates the next real send will use. If the agent's model has a context window too small to carry them, Tools and Memory are auto-disabled with a notice explaining why.
The switches, grouped the way the UI groups them:
| Group | Ability | What it does |
|---|---|---|
| Model Access | Tools | Master switch for the tool system. Off = a chat-only agent. |
| Memory | Inject relevant memories per turn and record new ones. (The default agent's memory is governed globally in Settings.) | |
| Output | Charts | Render data as inline chart cards |
| Speak Tool | A tool the agent can call to read a reply aloud on request | |
| Memory & Recall | Memory Recall | Let the agent search its own memory mid-conversation — separate from Memory, which only auto-injects |
| Knowledge | Knowledge | Search and read the knowledge collections granted inline below the toggle |
| Curator | Draft document updates as pending proposals you approve | |
| Web | Web Search | Native web search through your configured providers |
| Autonomy | Self-scheduling | Let the agent schedule its own follow-up runs and send notifications; frequency limits live in General → Configure → Scheduling |
| Data | Database | A private encrypted database for structured data (see Agent DB). With a cloud model, the schema — table names and column types — is sent with requests; row data is not. |
| Code Execution | Autonomous Execution | Master switch for sandboxed commands; the full permission set lives in Abilities → Sandbox |
| Host Files | Host Files | Grant one standing macOS folder to this agent, including for authenticated remote agent runs. Writes stay inside the folder; shell and git remain disabled. |
Most ability toggles are backed by tools, so they pause (with a note) if the master Tools switch is off.
Sandbox permissions
Abilities → Sandbox → Execution holds the full autonomous_exec permission set for when the Sandbox is on:
| Setting | What it does | Default |
|---|---|---|
| Autonomous Execution | Unlocks write/exec/install/secret tools in the Sandbox. Off = read-only sandbox tools. | On for new custom agents where the sandbox is supported |
| Plugin Creation | Lets the agent author and register new Sandbox plugins at runtime | On |
| Sandbox Network | Allow outbound network from the sandbox; turn off to cut exfiltration (takes effect on next sandbox start) | On |
| Allowed Domains | Comma-separated egress allowlist (example.com exact, *.example.com subdomains). Non-empty switches the sandbox to host-only networking with a filtering proxy. VM backend (macOS 26+) only — on Seatbelt, network is all-or-nothing. | Empty (unrestricted) |
| Background Processes | Long-lived detached processes (servers, watchers) the agent can manage | Off |
The same tab has a Workspace Folder row that reveals the agent's sandbox home (/workspace/agents/<name>/) in Finder — edits you make there are visible to the agent immediately — and the agent's secrets list. Sandbox Internals →
The tool picker
Each agent has its own enabled set of tools. You configure it in two places:
- Inside the Create Agent sheet — click Customize… under Capabilities while creating
- On an existing agent — open the agent → Abilities → Tools
Skills aren't in the picker. The Skills library is universal — every installed skill is automatically discoverable by every custom agent, with no per-agent assignment and no toggles. Agent configuration scopes tools; the shared library supplies skills.
Auto vs Manual
A single toggle at the top of the tool picker decides how your enabled set reaches the model:
- Auto (recommended) — The model starts with a small always-loaded set and a capabilities manifest, then loads more (tools, skills, methods) on demand via
capabilities_discover/capabilities_load. Saves context tokens and tends to give better focus. - Manual — Send the entire enabled tool set every turn. Predictable but heavier on context — and Manual mode doesn't use the skill library.
In either mode, the per-item Enabled toggles in the picker are honored — disabling a tool there means the model never sees it, in any mode.
For the mechanics of capability discovery, see Methods → Mid-conversation discovery.
What the picker looks like
Tools are grouped by source:
| Source | What's in it |
|---|---|
| Built-in | Always-loaded tools (the agent's todo/complete/clarify, share_artifact, web_search, etc.). Shown for transparency — toggling has no effect. |
| Plugin (one per plugin) | Tools shipped by each native plugin you've installed |
| MCP provider (one per provider) | Tools aggregated from a remote MCP server |
| Sandbox plugin (one per provisioned plugin) | Tools defined by JSON-recipe sandbox plugins |
Per group you can:
- Expand / collapse to inspect individual items
- Bulk enable / disable the whole group with one click
- See an at-a-glance count of how many items are enabled
Per item you see name, description, and an estimated token cost, with search by name and description.
Disabling tools or memory entirely
If you want a strictly conversational agent — no tools, no memory writes — flip the master switches off in Abilities → Overview:
- Tools off — no tools or capability context are sent for this agent
- Memory off — memory is neither injected on read nor recorded on write
Useful for therapy-style assistants, coaching agents, or anything where you want predictable text-in-text-out behavior.
Trusted folders and the Sandbox
These are separate execution modes:
- Pick a trusted folder in the chat input bar to give the current chat file/search/git tools scoped to that folder. Selecting it disables Sandbox for the agent.
- Enable Sandbox to give the agent shell access in an isolated environment (a Linux VM on macOS 26+, a Seatbelt-confined runner on macOS 15). This agent-scoped switch clears folder selections from visible chats using that agent; turn it off and reselect a folder when you want trusted-folder mode again.
Trusted-folder and Sandbox tools never appear together. The agent's sandbox permissions control how much capability it has if Sandbox is on. Read-only sandbox tools are available in that mode; write, exec, install, and secret tools require Autonomous Execution.
Separate from the current chat's trusted-folder picker, the per-agent Host Files ability grants one standing macOS folder for authenticated remote agent runs. It permits folder-confined file access but never enables host shell, git, or undo tools.
Subagents per agent
Each agent's Abilities → Subagents tab controls what it can delegate: spawning other agents and models, generating images inline, driving macOS apps with Computer Use, driving a persistent browser with Browser Use, and running AppleScript. Everything ships disabled — an agent can't delegate until you grant it. Subagents → · Computer Use → · Browser Use → · Image Generation →
Memory per agent
Each agent has its own memory — pinned facts, episodes, and identity overrides are stored per-agent. So your Code Assistant doesn't accidentally carry over context from your Therapy Buddy.
Identity overrides ("I prefer tabs over spaces", "Reply in English") are also per-agent unless you set them at the top level. If you want a clean stateless agent, turn the Memory ability off — memory is neither injected on read nor recorded on write. Memory →
Knowledge per agent
Beyond what an agent learns from you, you can hand it curated reference material: knowledge collections are folders of documents (markdown, plain text, code, PDF, Word, Excel, PowerPoint, CSV) the agent can search and read on demand. Grants are per-agent and explicit — in Abilities → Overview, turn on Knowledge and check the collections this agent may see right under the toggle; it can never touch the others. Enable Curator as well to let the agent flag stale documents and propose updates you approve. Knowledge →
Switching, duplicating, and managing agents
| Where | How |
|---|---|
| Inside a chat | Click the agent selector (top of the chat window) |
| From the grid | Each agent card has a ⋯ menu: Open, Duplicate, Open Database, Delete |
| Voice activation | Enable the agent for VAD and say its name. See Voice → VAD |
| Make a local copy | ⋯ → Duplicate. The fastest way to fork a working configuration and tweak it. |
| Reorder the grid | Click the reorder button in the Agents header and drag agents into place — the same order drives the agent selector |
Switching changes the system prompt, default model (if set), theme (if set), and memory scope. The current chat session keeps its history.
Agents you've been invited to (via Share Agent) appear in the same grid with a Remote badge. They show up in the agent selector too, so you can switch to them mid-chat the same way.
Built-in agents
Osaurus ships with a built-in Osaurus assistant whose agent definition is read-only. It is dedicated to configuring and explaining the app: it inspects current state with osaurus_status, osaurus_list, and osaurus_describe, and answers product questions from the bundled guide through osaurus_help.
It can also make approval-gated changes: osaurus_settings covers common app, server, chat, memory, voice, and default-agent settings; osaurus_watcher manages folder watchers; the other configuration tools manage agents, models, providers, MCP, plugins, search, and schedules. Agent updates can change supported capability toggles, and schedule updates can reassign a schedule to another custom agent.
The built-in assistant does not use the Skills library or trusted folders, and it is not a general work agent. For coding, research, files, images, or other work, create or switch to a custom agent.
Share an agent
When you share an agent with someone, you're not sending them a copy — you're giving them a live link to your agent on your Mac, routed over a secure tunnel. They chat with the same agent you built, with your prompt, your tools, your memory. You can revoke their access anytime.
Send an invite
- Open the agent and click Share Agent
- Pick how long the link should stay valid: 1 hour, 1 day, 7 days (default), or 30 days
- Osaurus enables the public link automatically and generates a signed
osaurus://…?pair=…invite - Send the link however you want — it shows up as a clickable URL, a QR code, and a system Share… button (drop it in iMessage, AirDrop, Mail, etc.)
Each invite is single-use — once someone accepts, the link can't be reused. If you want to share with three people, generate three invites.
The invite ledger
Every invite you've ever issued for an agent is listed under Issued Invites with its status:
| Status | What it means |
|---|---|
| Active | Link is valid and unused |
| Accepted | Someone redeemed it. They have access until you revoke. |
| Expired | Past expiry date; no further action needed |
You can revoke any active or accepted invite at any time. Revoking an accepted invite kills the receiver's access key immediately — they get turned away on the next request.
Receiving an invite
When someone sends you a osaurus://…?pair=… link:
- Open it (click the URL or scan the QR code — Osaurus catches the deeplink)
- The Add Remote Agent sheet shows you who you'd be paired with: name, description, source URL, expiry, an optional note for yourself
- Click Add Remote Agent
The agent appears in your Agents grid with a Remote badge and an antenna icon. Chat with it like any other agent — your messages travel over the tunnel back to the sender's Mac, where their agent runs them.
You can leave a note on the remote agent (e.g. "Alice's research agent") so you remember who shared it. Either side can revoke anytime: the sender from their Issued Invites ledger, the receiver from the remote agent's detail view.
Move an agent to another Mac
Sharing gives someone a live link to an agent running on your Mac. If you want the agent itself to move — configuration, database, saved views and all — export it as an encrypted bundle:
- From the agent's detail view, choose Export Bundle and pick a folder for the
.osaurus-agentfile - Choose a passphrase (at least 8 characters) — the bundle is sealed with it, and you'll need the same passphrase to open it anywhere else
- On the other Mac, choose Import Bundle, pick the file, and enter the passphrase
- Review the manifest — agent name, description, table and saved-view counts, export date — then Activate (or Discard to change nothing on disk)
Activating copies the agent into ~/.osaurus/agents/<id>/, re-keys its database to the local master key, and registers the agent for use.
Identity and access keys
Each agent gets a cryptographic address derived from your master key. You can mint per-agent access keys (osk-v1) that scope external tools and MCP clients to just that agent. Identity →
Tips
- Start from a template. The Create Agent sheet's Start From strip prefills a name, avatar, and prompt — pick the closest one and tweak. Duplicating an existing agent works too.
- Watch the context estimate. Every ability you enable costs startup context; the live figure in Abilities → Overview shows exactly what each toggle adds, so you can keep small-model agents lean.
- Match temperature to the task. Low for code/facts (0.1–0.3), high for creative work (0.7–0.9). Generation overrides live in General → Configure.
- Use themes for context. Visual cues (a green theme for your assistant, a red theme for your code reviewer) help you stay oriented when running multiple windows.
- Don't over-prompt. Long system prompts eat into context. Keep them tight and lean on Skills for specialized methodology.
- Pick a tight expiry. When you share an agent, default to a short window (1 day or 7 days) — you can always re-share. Long-lived links are harder to keep track of.
Related:
- Tasks — what happens when you ask the agent to do something
- Skills — auto-selected expertise
- Memory — what your agent remembers
- Knowledge — curated reference collections your agent can consult
- Agent DB & Self-Scheduling — give an agent structured storage and the ability to wake itself
- Themes — visual customization per agent