Agents

A chat answers in prose. An agent acts. It reads a file, looks up an event on your calendar, searches your notes, writes a draft to disk. The model decides when to reach for a tool, the runtime runs it, the result comes back, and the model keeps going from there. The whole loop runs in the studio on hardware you own, and it touches nothing you did not hand the agent first.

What an agent is here#

An agent is a saved configuration, not a separate program. It holds a name, the path to a GGUF model file, an optional folder or two it watches, the tools it may call, and the grants that decide what those tools can touch. Create one, run several, and each keeps its own history. Two agents pointed at the same model are still two different agents: one reads your calendar and stops there, the other writes to a project folder and searches the web.

Model

The weights the agent runs. Any model in the catalog works; pick by task and let the runtime fit it to memory.

Folders

The directories the agent may read and, if you grant it, write. Outside them, the filesystem does not exist as far as the agent is concerned.

Tools

The verbs the model can emit: read a file, list a directory, read a connected account, search the web, speak a line aloud.

Grants

The per-agent permissions that gate every tool. Off by default; see the grant model.

The tools a model can reach for#

Tools fall into three families. The filesystem: read a file, list a directory, find files by name, and (only with a write grant) edit or create them, scoped to the folders you picked. The connectors read the personal stores already on your Mac: calendar, reminders, notes, contacts, messages, and mail. The rest stand alone. Web search runs through a keyless provider, the system voice speaks a short line aloud, and a generic reader reaches any folder no dedicated connector covers.

The full map of every tool to its grant lives in the connectors catalog. The personal-store connectors are read only: an agent can read your calendar, but it never creates, edits, or deletes an event.

Shell access is the sharpest tool, and the most narrowly scoped. Running a program reaches past the watched folder, so it stays off by default and no single checkbox widens it. You name the exact binaries an agent may run, and the kernel refuses anything else. Driving another app by script gets the same treatment. When the catalog does not ship a tool you need, you can add your own and scope it the same way.

How a turn runs#

You type a request. If a tool would help, the model emits a small structured call instead of an answer. The runtime parses the call, checks it against the agent’s grants, and either runs it or refuses. The result feeds back into the context, and the model decides whether to call another tool or write the reply. The cycle repeats until the model stops calling tools.

Two properties keep the loop safe on real data. The call is valid by construction: the engine constrains the model so a tool call always parses, never a stray brace that breaks the step. See optimizing around the tool call for how. Every result that comes back counts as untrusted output: a file you did not write, or a web page the model fetched, is data, not instruction, so text buried in a document cannot quietly take over the turn.

It all stays on the machine#

The model, the tool, the result, and the decision about what to do next all run on your hardware. A connector reads a local store and syncs it nowhere. Web search is the one tool that reaches the network. It stays off until you grant it, and the studio records the outbound request so the call is never invisible. The full boundary lives in the local-first guarantee.

The grant model is the rule that turns “the model wants to do X” into “the model is allowed to do X.” Start there.