LocalAI/docs/content/features/chats-agents.md

+++ disableToc = false title = "Chats: saved agents, triggers and inbox" weight = 22 url = "/features/chats-agents/" +++

A saved agent is a definition you can start a chat with. It has instructions and four lists: the MCP servers, add-ons, collections and skills the chat may use. Triggers and the inbox build on agents and are described on this page too.

Saved agents

An agent has:

Field	Meaning
name	1 to 80 characters. Unique for you, ignoring case.
description	A short note for you.
instructions	Text added to the system prompt of every turn. At most 32 KiB.
model	Optional. The chat uses this model. Chat-capable model aliases can also be selected; the agent saves the alias name, not its target name. Without it, the chat is created with the model you choose.
mcp_servers	Names of servers in the model's MCP configuration, and your MCP connectors as connector:<id>. The form lists both.
addons	IDs of installed add-ons.
collections	Names of your collections.
skills	Names of skills. The index of skills and the load_skill tool of the chat offer only these.
builtins_off	Groups of built-in tools the agent's chats never have: shell, files, web, media, collections, subagents, triggers and changes. It is a ceiling: a chat with the agent shows the group switched off and cannot switch it on. Empty (the default): the chat has every group it has by default. A group this server does not offer is dropped.
builtins_on	Opt-in groups of built-in tools that chats with the agent start with: saved_agents. The chat can switch them off.
network	The network of the [Sandbox]({{%relref "features/addons#network-access" %}}) commands of the agent's trigger and connector runs: off (the default), registries (the package registries) or all (every public host), capped by the administrator's chats_egress_ceiling. A run never shows a card: a host outside it is blocked, and the block is in the run's output. A chat you start with the agent starts with this preset too; you change it in the chat's Tools menu. The agent form sets it in the add-ons fold.
folders	Optional. Up to 8 folders of your files that chats with the agent work in, each with its own mode: read or write. folder is the same with one entry. Without them the agent works on all your files. See Folders of an agent.

The agent form shows the same Tools list as the Tools menu of a chat, with a short description under each switch: the built-in tool groups, the add-ons, your connectors, and the skills. What you switch on is saved in addons, mcp_servers and skills; what you switch off among the built-in groups is saved in builtins_off.

Each list is an exact grant. An empty list grants nothing: a chat with an agent that names no add-ons has no add-on tools, even when you could use some. A plain chat, with no agent, is not changed.

Document selections keep the names docx, pptx, pdf, and xlsx. Selecting a skill does not grant its provider or command execution. Grant Simple Office explicitly for its tool-based procedures; no command runner is required. For Sandbox procedures, grant Sandbox and allow its selected, usable isolated bash tool. A host command runner alone does not qualify. Without an eligible provider, the selected skill is unavailable; no built-in document procedure serves instead. An unavailable provider pin never silently selects another provider. See [Document skills]({{%relref "features/chats#document-skills" %}}) for provider choices and OFF preferences.

Add-on changes apply at once

An add-on you turn on for a chat, or name in an agent, is allowed to change your data in that chat. A tool call that adds rows, changes a schema, creates a database or starts a job is applied at once, as you, with the same permission and stale-data checks as the Add-ons page. There is no confirmation card. The model is told what was applied, and the tool entry in the chat says it. A change the add-on kept a change set for can be undone from the chat with an Undo button (Tables rows, schema and databases, and Fine-tuning and Quantization job starts); the result says whether a change can be undone and, if not, why. File changes of the Sandbox and Office add-ons are one change set in the history of your files and can be undone there. A trigger or a scheduled run behaves the same, with no proposal waiting for a browser. Other ways to call add-on tools, such as the OpenAI-compatible API and MCP, still store a proposal that only your own browser session can confirm.

An agent never gives more than you have

A chat gets the intersection of the agent's lists and what you may use at that moment. If an add-on is disabled, a collection is deleted or you lose the MCP feature, the chat still starts. The thing is absent, and the model gets one line at the start of the turn, for example unavailable this turn: add-on office, collection docs. A sub-agent of the chat can only get tools the chat has, and the groups of built-in tools that the chat switched off in its Tools menu (for example Your files) stay off for the sub-agent too.

A chat can also start a saved agent as a sub-agent, when you switch Saved agents on in its Tools menu. See [Saved agents as sub-agents]({{%relref "features/chats#saved-agents-as-sub-agents" %}}).

If you delete an agent, the chats that ran with it keep their history. For an agent without a folder, their next turn runs without the agent's tools, and the model is told that the agent was deleted. For an agent with a folder, the next turn is refused instead; it never falls back to all your files.

Pages

The Agents page (Agents in the sidebar, /app/agents) lists your agents with the chats that ran with each one, and links to the Triggers and the Tasks. A page for one agent (/app/agents/{id}) shows its definition, the triggers that start it and its run history from the server (the chats you had with it and the ones its triggers and connectors started). Create and edit an agent in a form of folds with a preview of the definition and of what changed. Export and Import use the server's agent file (see below); the import opens the new agent and says what the server changed. It also reads the JSON export of an older agent, and names what it could not take over. With no agents yet, the page offers the server's starter agents. Chat with an agent from its row: the chat page opens empty with the agent chosen.

API

curl -X POST .../api/chats/agents -d '{"name": "Reviewer", "instructions": "Answer in French.", "addons": ["office"], "skills": ["review"]}'
curl .../api/chats/agents
curl -X POST .../api/chats -d '{"agent_id": "<id>", "model": "my-model"}'

GET, PUT and DELETE /api/chats/agents/{id} read, replace and delete one. A PUT replaces every field except folders (see below) and the tool switches builtins_off and builtins_on, which it keeps when the body does not name them (an empty list clears them). Chats that already run with the agent use the new definition from their next turn. Another user's agent is always 404.

Agents need the agents feature, which is off by default for a user (see Chats permissions). They have no administration tools, as they are your own settings.

Folders of an agent

folders gives the agent up to eight folders of your files, each with a mode, read (the agent's chats can read it) or write (they can read and change it). folder, one {path, mode}, is read as a list with one entry. Responses carry folders in the order you gave them, and folder, the first of them:

curl -X POST .../api/chats/agents -d '{"name": "Acme", "folders": [
  {"path": "/Projects/Acme", "mode": "write"}, {"path": "/Reference", "mode": "read"}]}'
# {"id":"...","name":"Acme",...,
#  "folder":{"path":"/Projects/Acme","name":"Acme","mode":"write","effective":"write","state":"ok"},
#  "folders":[{"path":"/Projects/Acme",...},{"path":"/Reference","name":"Reference","mode":"read","effective":"read","state":"ok"}]}

• A list has at most 8 folders and each folder once. Nine folders, a repeat, a row without a path or a row without a mode is 400.

• Where one folder is inside another folder of the same agent, the inner folder works at the mode of the outer one, and effective says so. The file store gives a folder the highest mode among the folders above it, so a read only folder inside a write folder cannot be kept read only, and a write folder inside a read only folder cannot be written. A folder in the shared folders is always read only.

• A folder that is missing or unset stops the agent, and the error names the row ("folder 2 was deleted..."). The other folders do not take its place.

• path is a folder of your files, as the Files page shows it. / is all of your files, which with read makes an agent that can read everything and change nothing. The folder cannot be LocalAI, Chats or a folder inside them, and it cannot be a shared folder. A path that is not a folder of yours is 400.

• The server keeps the folder itself, not its path. When you rename or move the folder, the agent follows it while you can read it. path shows its home-relative path, or /shared/<name>/... after a move into a shared folder. Other readable locations have no public path; the folder remains ok and the agent still follows it by identity.

• state is ok, missing when the folder was deleted or you can no longer read it, or unset when no folder is chosen yet (an imported agent whose folder was not found here).

• An agent whose folder is missing or unset does not start, and it never falls back to all your files: POST /api/chats answers 409 with the type agent_folder_missing, and so does a message to a chat that is open already. A chat whose agent had a folder and was then deleted is refused the same way. Choose a folder in the agent's settings, or restore the folder from the Trash (it comes back as the same folder, so the agent needs no edit), and send the message again.

• A chat with the agent reaches its folders (read only for read), its own chat folder under Chats (attachments and the work folder, read and write), the readable shared folders and the skills (read only), and nothing else. A folder next to the agent's folders, or above them, is not reachable.

• Scoped access has a limit of 32 folder roots per scope: the chat folder, the agent's folders (at most 8), every skill folder that exists, and the shared folders. A chat is never refused for this. The skill folders and the agent's folders are always kept. A shared folder that is inside a folder already kept is left out, as it is reachable there. Of the others the ones with the lowest IDs are kept until the limit is full. The rest are not mounted: the model is told how many, and the response of the agent carries folder_notice.not_mounted, shown in the agent form. Leaving a shared folder out only removes access. Each turn checks again, so a change of the shared folders applies from the next message. A failure to enumerate shared folders refuses access instead of silently omitting them.

• The model sees the agent's first folder at /workspace/home, so /a.txt and /workspace/home/a.txt are a.txt in that folder. The other folders are at /workspace/folder-<name>, with " 2", " 3" and so on when two folders have the same name. The chat folder is at /workspace/chat, with the work folder at /workspace/chat/work/. The shared folders are at /workspace/shared-<name>. The file tools, the image and document tools, the file search and the system prompt use this layout, and a sub-agent of the chat gets the same folders. A file you attach to a message is named to the model at /workspace/chat/<file>.

• A sub-agent never reaches more than the chat that started it, in folder or in mode. A plain sub-agent and a saved agent without a folder work in the chat's folder, at the chat's mode. A saved agent with folders can start from the chat only when each of its folders is one of the chat's folders or inside one; it then works in its own folders at the lower of the two modes. Any other agent is refused with "this agent works in another folder than this chat", and list_agents does not list it.

• Commands of the chat run only in the Sandbox add-on. Its sandbox has the agent's folder at /workspace/home (read only for read), the chat folder at /workspace/chat (read and write), and nothing else of your files. What a command writes anywhere else is not saved, and the command's output says so. The built-in bash that runs on this machine is never offered to such a chat, also when chats_host_exec is on: a command on this machine can read every file LocalAI can read, so nothing can keep it in the folder. The Tools menu of the chat says why. On a server without the Sandbox, the agent still reads and changes its folder with the file tools.

• Add-ons that a chat with the agent calls work in the same folders. For an add-on that works on your files, such as Office or the Sandbox, / is the agent's folder, and the Sandbox sees the chat folder next to it at /workspace/chat. This holds for every tool, also one that only reads. See [Workspace operations]({{%relref "features/addons#workspace-operations" %}}).

• A PUT without folders or folder keeps the folders the agent has, so a client that does not know the fields cannot give the agent more files by editing it. "folders": [] clears them. When both are sent, folders wins.

• The folder limits what the chat reaches through your files only. The MCP servers, web tools and collections that the agent grants are separate grants and are not limited to the folder. The chat is not told to build [Pages]({{%relref "features/pages" %}}) either: pages live in pages/ of your home, outside the folder.

• The folder limits the agent, not you. The Files page, its History, Undo and Trash still show all your files, and a chat's file list and attachments keep their paths in your home there.

• Triggers and connectors that use the agent keep to its folder too. See Triggers of an agent with a folder and the connectors page.

In the web interface, the Files section of the agent form sets the folder: All my files, or Chosen folders: one row for each folder, with Choose folder, which opens a folder picker of your files (LocalAI, Chats and shared folders cannot be chosen), the access of that row, Can read or Can read and change, and a remove button. Add folder stops at eight. A row inside another row shows the mode it works at. The agents list and the agent's page show the folder and its access, with a lock for read only, or Folder missing with a link to the form. The Files page marks a folder that an agent uses. A chat with the agent shows the folder next to the agent in the message box and in the Tools menu. A chat that cannot start because the folder is missing says so and offers Edit agent.

The folder is read from the stores at every request and at the start of every turn, and nothing is kept in memory between turns (stateless per request), so every frontend and chat worker of a cluster answers the same. A change of the folder or the mode applies from the next message of a chat that is open; a turn that is running finishes with the access it started with.

Downgrade. A server older than this feature does not know the folder of an agent, and one from before several folders reads only the first. If you go back to such a version, its agents work on all your files again, without a warning, and an agent file of version 2 cannot be imported there. Before you downgrade, export and delete the agents that have a folder, or switch off their triggers and connectors.

Starter agents

GET /api/chats/agents/templates lists ready-made definitions (a research assistant, a code reviewer, a daily digest, a writing editor). They grant nothing. POST /api/chats/agents/templates/{id}/create saves one as your own ({"name": "..."} is optional); then grant it tools with PUT.

Builtin grants

An agent can be given built-in capabilities in its builtins list. The list is empty by default, no template or import turns a grant on, and a chat of the agent holds only the grants you may use at that moment. GET /api/chats/agents/builtin-grants returns {grants: [{name, title, description, sensitive}]} for the editor. The names are memory.write, profile.write, skills.write, pages.write, dashboard.write, triggers.propose, triggers.run, talkback.channels, talkback.new_channel, files.upload, act.files, act.addons, act.send, act.spend and saved_agents (the opt-in group of that name; granting it also switches the group on). A sensitive grant changes what the agent may do or reach later; the editor marks it. The five *.write grants let the agent propose a memory note, its profile, a skill, a page or a dashboard change with propose_change; you confirm every proposal, and you can undo it. A write to the agent without the builtins field keeps them, an empty list clears them and an unknown name is refused (an import drops it).

In a chat that a messaging connection started, the grants also decide which tools the model gets. A tool exists when the sender holds the capability on the connection, the agent holds the grant, and the chat did not switch the tool off. Four grants work this way: triggers.propose, triggers.run, talkback.channels and files.upload (the sender's files going to the agent), plus the sensitive talkback.new_channel. An agent that has no builtins list at all keeps the non-sensitive ones, as before. A sensitive grant is never implied: it needs to be on the list. The moment you grant any built-in, the list is the whole answer, so add the connector grants you want to keep (granting only memory.write to an agent that proposed triggers from a messaging app turns those off; nothing is deleted and they work again when you grant triggers.propose). The act.* grants are recorded but not enforced yet: the action policy of unattended runs that uses them is still to come.

Export and import

curl .../api/chats/agents/<id>/export > reviewer.json
curl -X POST .../api/chats/agents/import -d @reviewer.json
curl -X POST .../api/chats/agents/import -F file=@reviewer.json

The file holds the definition only (kind localai-agent): no ID, owner or time. An agent with tool switches (builtins_off, builtins_on) is version 4, so that a server that does not know them refuses the file instead of giving the agent every tool. The builtins list is an extra field of any version; a server that does not know it ignores it, so the agent arrives without the grants. An agent without a folder or tool switches is version 1. An agent with one folder is version 2 and carries folder with the folder's path at export time and the mode, for example {"path": "/Projects/Acme", "mode": "read"} (the path is empty when the folder is missing, not chosen, or now outside your home). A followed folder in a shared location stays usable by the original agent, but its export carries an empty path and the mode. Import keeps it scoped with state unset and warns you to choose a folder; it never interprets the shared path as a folder in your home. An agent with several folders is version 3 and carries folders, a list of the same {path, mode} entries. A server that reads only version 1 refuses a version 2 file, and one that reads only version 2 refuses a version 3 file, so an agent limited to folders is never imported somewhere as an agent with more files. On import each path is looked up; a folder that is not found stays in the list as a row that is not chosen, with the mode, and a warning names it. An import always makes a new agent. The folder is looked up by its path in your files; when you have no such folder, the agent is saved with the mode and no folder (state: unset), it does not start until you choose one, and a warning says so. A name you already use gets " (2)", " (3)" and so on, and a model that this server does not have, or that you may not use, is dropped. The response lists such changes under warnings. The grants (MCP servers, add-ons, collections, skills) are kept as names; a grant that names something you do not have gives the chat nothing, as for any agent. Secrets are never part of an agent, so the file has none.

Run history

GET /api/chats/agents/{id}/runs lists the chats that ran with the agent, newest first: the ones you had with it, the ones its triggers started (origin: trigger) and the ones its connectors started (origin: connector), each with running and last_turn. total, failed and running count every run among your newest 5,000 chats. Open a run with GET /api/chats/{chat_id}.

Connectors

A connector binds a Telegram bot or a Slack app to an agent, so a person can talk to it from Telegram or Slack. An MCP connector is a tool server that an agent can name in its mcp_servers list.

Triggers

A trigger starts a chat as you, by itself. Each run is an ordinary chat of yours: it uses your files, your quota and your model allowlist, you can open it and undo what it changed, and it is marked with its trigger. To repeat a prompt inside one chat, every few minutes, use a [loop]({{%relref "features/chats#loops-repeat-a-prompt-in-a-chat" %}}) instead (see Loop or trigger? there). There are two kinds.

Kind	Runs	Fields
schedule	At a time	schedule, time_zone (an IANA name; UTC when empty)
file	When a file arrives in a folder of your files	folder (a path inside your files, such as /Contracts), quiet_seconds (default 30), min_gap_seconds (default 60)

A schedule is one of daily 08:00, weekdays 09:30, weekly mon,thu 09:30, monthly 15 08:00, once 2026-12-24 18:00 or five cron fields. The cron fields are numbers, lists, ranges and steps (*/15, 1-5, 1,15); names such as mon or jan are not read, and weekly takes day names. A time that does not exist in the time zone (a daylight-saving gap) moves to the first valid minute after it, and a repeated hour runs once. GET /api/chats/triggers/preview?when=...&tz=... shows the next times and says what the text means.

A file trigger waits until the file has not changed for the quiet period, then starts one run for that version of the file. The first message of the run says A new file arrived: /Contracts/a.txt. A run's own writes never start the same trigger. A file that changes again after a run of the trigger began waits for the trigger's minimum gap (min_gap_seconds, 60 by default, at most a day) before it starts another run, and further changes while it waits start nothing extra. Files that were already waiting when the run began still run. With the daily limit, this keeps a writer that reacts to the run's output, such as a page that saves after each change it sees, from starting runs in a loop: at most one run a minute and 24 a day by default. An AGENTS.md file in a folder, or above it, is added to the first message as rules for the run. Treat it as text from whoever can write there.

What a run gets

• Its message. The first message is the prompt of the trigger, the folder rules and, for a file trigger, the file. LocalAI adds one closing line to every trigger run: "When you are done, answer with one short plain sentence about what changed. Do not print JSON or code unless the task asks the user for it." The answer is what you read in the chat and the inbox, so write the prompt without a request for JSON output. A connector chat is a talk with a person and does not get the line.
• Who it is. The run is a chat of the trigger's owner, with the owner's grants. If the owner is over quota, the run fails with that reason and the owner gets a notification.
• Which tools. With an agent (agent_id), the tools of that agent. Without one, the run uses the model and the add-on and skill switches of the chat that made the trigger (source_chat_id), or the defaults of a new chat. An unattended run with no agent gets no add-on tool that acts at once, such as the Sandbox: name the add-on in an agent to allow it. A run never gets propose_trigger and cannot change its own trigger.
• Network. The Sandbox commands of a run reach the network of the agent's network field, under the administrator's ceiling, and nothing without an agent. Nobody watches a run, so no card asks: a blocked host stays blocked. A sub-agent follows the network of the chat that started it, its rules included, and never shows a card either.
• Limits. A run has 15 minutes. At most 2 runs go at once, one per trigger, and a trigger has a daily limit (daily_cap, default 24). A run that is skipped or fails shows its reason on the trigger.
• Cost. A run is a chat turn on the trigger's model, so it uses tokens. A run records the prompt and completion tokens of its model requests (tokens on the run), and a trigger reports the average of its last runs, the most runs one day can have, and whether the model is a remote service (cost on the trigger). LocalAI keeps no price list, so the cost is in tokens only.
• History. A trigger keeps its last 200 finished runs, and every run of the last two days. A finished run older than 30 days is removed, whatever the count. A run that is queued or running is never removed. Set --trigger-run-keep and --trigger-run-retention-days (-1 keeps all) to change this. A file version that ran can run again once its old run is removed.
• When it cannot run. A deleted agent fails the run with "the agent was deleted" and switches the trigger off. A disabled owner skips the run. An owner who no longer exists, or a folder that is gone, skips the run and switches the trigger off. An agent whose folder is missing or not chosen skips the run with "the agent's folder is missing" and switches the trigger off. Each of these tells the owner.

Triggers of an agent with a folder

A trigger whose agent has a folder keeps to that folder, like every chat of the agent:

• A file trigger must watch the agent's folder or a folder inside it. Saving one that watches another folder (at create, at update, and when you confirm a proposal) is refused with 400: "the trigger's folder must be inside the agent's folder". A file outside the folder never starts a run.
• Each run checks again. A trigger made before the agent got its folder, or whose agent moved to another folder since, skips the run with "the trigger's folder is not inside the agent's folder" and is switched off.
• A run whose agent's folder is deleted, unreadable or not chosen never runs on your other files: it is skipped with "the agent's folder is missing", no chat is made, the trigger is switched off and you get a notification. Saving a trigger for such an agent is refused until you choose a folder. Restore the folder (or choose another one) and switch the trigger on again.
• If the complete file access exceeds the 32-root limit, the run fails without starting a chat. The trigger stays enabled: reduce the available shared folders and retry. This differs from a missing agent folder, which switches the trigger off.
• The rules of a run come from AGENTS.md files in the agent's folder only: for a schedule trigger the agent's folder itself, for a file trigger the folders from the agent's folder down to the watched folder. An AGENTS.md above the agent's folder is not read. The first message names folders and the file as the agent's chats see them: # Folder rules: /workspace/home and A new file arrived: /workspace/home/In/a.txt.
• The run's chat reaches what a chat of the agent reaches, nothing more.
• In a chat with the agent, the trigger tools name folders as the chat does (/In and /workspace/home/In are In in the agent's folder) and refuse a folder outside it. list_triggers, update_trigger and delete_trigger see only the triggers of that agent; change the others on the Triggers page.

The folder is looked up at every save and every run, so all frontends of a cluster apply the same rule (stateless per request).

A trigger runs nothing for the time before it was saved or switched on. After downtime, a missed schedule runs once, not once for each missed time.

Proposals

The four trigger tools (propose_trigger, list_triggers, update_trigger and delete_trigger) form the Triggers group in the chat's Tools menu. They are on in a chat you start, and one switch turns all four off for that chat (PUT /api/chats/{id}/builtins {"off": ["triggers"]}; see the Tools menu). Switch it off in the Home composer before you start the chat to have none from the first message.

In a chat, the model can propose a trigger with propose_trigger and list yours with list_triggers. A proposal is not active and runs nothing. It waits for you in the chat and on the Triggers page (/app/triggers, GET /api/chats/triggers/proposals, with ?chat={id} for the ones made in one chat). Change it first if you want (PUT .../proposals/{id} with the same body as a trigger; it stays a proposal), then confirm it (POST .../proposals/{id}/confirm, with your time_zone when it names none) or dismiss it (DELETE .../proposals/{id}). The chat carries the proposal: the tool line of propose_trigger has a card of kind trigger_proposal whose id is the proposal's id, in the live tool_end event and in the transcript, so it shows again after a reload, and a trigger_proposed event announces it to a client that is watching. If a proposal was made in a chat that has an agent, the trigger keeps that agent. At most 10 proposals wait at a time, and you can have 50 triggers.

The card sits below the text of the message it belongs to. When you answer it, it does not go away: it turns into a receipt, and the answer is kept on the server with the proposal (GET .../proposals/{id} returns state: pending, accepted, declined or undone), so the receipt shows again after a reload, in another browser and on every frontend of a cluster.

• Accepted shows what was scheduled in plain words ("Scheduled: Every Monday at 09:00 (Europe/Rome)"), the name of the trigger, its next run, View trigger (the trigger has the proposal's id) and Undo.
• Undo (POST .../proposals/{id}/undo) switches the trigger off and removes it from the Triggers page. The proposal stays as an undone record, and Schedule it again (POST .../proposals/{id}/reopen) makes it wait for your answer again. Undo is refused with 409 once the trigger ran (a run started by hand counts) or you edited or switched it on the Triggers page; the receipt then tells you to remove it there. The response carries can_undo and undo_blocked (ran or edited).
• Declined leaves a quiet one-line receipt with Restore.
• A trigger you delete on the Triggers page ends the receipt: the card says the trigger was removed (404).

At the start of its next turn the model is told what became of the triggers it proposed in the chat (accepted, declined or undone), so it does not say a trigger runs when it was undone, and does not propose a declined one again unless you ask. A declined or undone proposal does not count towards the limit of 10 waiting proposals or 50 triggers.

A schedule proposed in a chat runs at most once an hour. A shorter one (for example */15 * * * *) is refused with the reason, and the model is told to propose an hourly or slower one. An edit of the proposal keeps the same floor. On the Triggers page you can still choose a shorter schedule yourself.

A proposal also carries a plan, so you see what it does before you create it: what a run reads (reads), the file in your home it rewrites (writes), the Home widget that shows that file (widget, the widget's id in LocalAI/home.json) and about how many tokens one run uses (estimated_tokens). The card lists them with when it runs and its first run, that it runs as you with the chat's model, the cost (and whether the tokens leave the server) and how to stop it. When you create a trigger whose plan names a widget, LocalAI writes the trigger's id into that widget as trigger, so the widget can show when it runs. A form that edits a trigger and does not send the plan keeps it.

Changes from a chat

The model can also change the triggers you already have. list_triggers gives each trigger a short ref (for example t1a2b3c4d): it stays the same for the trigger and it is not the trigger's id. The list shows no prompts. To read the prompt and the other settings of one trigger, the model passes its ref with include_prompt: true. A ref of another user's trigger, or one that does not exist, is an error for the model. The model can also name a trigger by its exact name when only one trigger has that name.

• update_trigger {ref, name, prompt, when, time_zone, daily_cap, enabled, reads, writes, widget, estimated_tokens} changes the fields it names and keeps the others. The same rules as for a proposal apply: a schedule that changes runs at most once an hour, the folder and the writes file must be in your files. A change of anything other than enabled does nothing by itself: a card shows each changed field before and after, with Apply and Dismiss. A change that only pauses (enabled: false) or resumes (enabled: true) the trigger applies at once, because you can take it back, and its card is a receipt with Undo.
• delete_trigger {ref} deletes nothing by itself: a card shows the trigger's name, when it runs, whether it is on and its last run, with Delete and Keep.

The tool descriptions tell the model which change waits and which applies at once, so it does not say a change is made before you apply it. At the start of its next turn the model is told what you did with the changes it asked for in the chat.

After you apply a change the card is a receipt with Undo for one day. Undo puts the trigger back as it was before the change. For a delete it restores the trigger with the same id and settings; its run history is not restored, and the chats of its runs were never removed. Undo is refused (409, with the reason) after the day, when the trigger was changed on the Triggers page since, or, for a delete, when you already have 50 triggers. A change that waits cannot apply once the trigger was changed or removed after the model asked for it: the card says so and keeps only Dismiss.

The card's change is kept on the server, so the card shows the same state after a reload, in another browser and on every frontend of a cluster. The tool line has a card of kind trigger_change whose id is the change's id, and a trigger_proposed event announces it to a client that is watching.

Route	What it does
GET /api/chats/triggers/changes/{id}	The change: op (update, delete, pause or resume), state (pending, applied, dismissed or undone), trigger_id, before, after (absent for a delete), fields, stale, can_undo, undo_blocked (expired, edited, removed or full) and last_run. 404 a week after it was answered, when it is no longer kept.
POST .../changes/{id}/apply	Makes the edit or deletes the trigger. 409 when the trigger changed since or the change was answered.
DELETE .../changes/{id}	Dismisses the change (Keep for a delete). The trigger stays as it is.
POST .../changes/{id}/undo	Takes an applied change back, for one day.

A change does not count towards the 50 triggers or the 10 waiting proposals. At most 10 changes wait at a time. Like the other trigger tools, these tools are offered only in a chat a person started: a trigger run, a connector run and a sub-agent never get them.

Clusters

In a cluster, one frontend runs the triggers at a time: the one that holds an advisory lock in the database. A due time or a file version is one unique row, so it runs once even when two frontends try. If that frontend stops, another takes over, ends the runs whose chat is over as failed ("interrupted by a restart") and tells the owner, and goes on. Triggers need the database; the JSON store is for a single process.

With chat workers, the frontend that leads still starts and watches each run, and a chat worker runs its turns.

The same holds for one server. A run that a stop or a restart cuts short is recorded as interrupted, its chat shows the turn as interrupted (not done, even if some text was written), and its owner gets a "failed" notification. The triggers are checked every 5 seconds, so a schedule starts within 5 seconds of its time and a file trigger within 5 seconds of the end of its quiet time.

API

curl -X POST .../api/chats/triggers -d '{"name": "Morning digest", "prompt": "Summarise yesterday.", "kind": "schedule", "schedule": "weekdays 09:00", "time_zone": "Europe/Rome", "enabled": true, "model": "my-model"}'
curl .../api/chats/triggers
curl -X POST .../api/chats/triggers/<id>/run      # start a run now
curl .../api/chats/triggers/<id>/runs

A trigger in a response also has plan (reads, writes, widget), cost (estimated_tokens, average_tokens and runs, max_runs_per_day, remote), last_done (the end of the newest run that ended well), min_gap_seconds for a file trigger, and each run its tokens. A create or replace takes plan, estimated_tokens and min_gap_seconds; an empty one keeps the stored value.

GET, PUT and DELETE /api/chats/triggers/{id} read, replace and delete one, and POST .../enable and .../disable switch it. Deleting a trigger stops its running run and drops its queued runs; the chats it made stay. Another user's trigger is always 404. Triggers are your own settings, so they have no administration tools.

Inbox

The inbox lists what ended while you were elsewhere: a trigger run that finished or failed, or something that needs you. Each item has a kind (run_ended, run_failed or needs_attention), a status (ok or failed), a source (trigger, connector or system; empty on items stored before sources existed), a short title and text, and a link to the chat it is about. A chat that a run started is unread until you open it: opening the chat marks its notifications read.

In the chat page, the Notifications button in the header shows the unread count (99+ above 99) and opens the panel (a sheet over the bottom of the screen on a phone):

• All, Unread and Failed filter the list. Failed shows every failed run and every trigger or connector that was switched off.
• Items are grouped under Today, Yesterday and Earlier. Each one shows what sent it, when (the exact time on hover) and, for a failure, the reason.
• A click on an item marks it read and opens its chat. A connector that was switched off opens the connectors page.
• Hover an item (or focus it) to mark it read or delete it. With the keyboard, the arrow keys, Home and End move between items, Enter opens one, Delete removes it and Esc closes the panel.
• Mark all read is in the panel header; Clear read and Clear all are in its menu.
• A notification that arrives while the panel is open slides in at the top and is highlighted for a few seconds.

You keep at most 500 notifications, none older than 90 days. The age limit applies when you read: an older notification is not listed or counted, and it is deleted the next time one is added.

curl ".../api/chats/notifications?unread=1"          # the unread ones, and the unread count
curl .../api/chats/notifications/count
curl -X POST .../api/chats/notifications/read -d '{"all": true}'
curl -X DELETE .../api/chats/notifications -d '{"ids": [12, 13]}'
curl -X DELETE .../api/chats/notifications -d '{"all": true}'                    # empty the inbox
curl -X DELETE .../api/chats/notifications -d '{"all": true, "read_only": true}' # remove only the read ones
curl -N .../api/chats/notifications/events            # new ones as server-sent events

Clear all asks first, in the panel, and says how many notifications it removes. Clear read keeps the unread ones. A removed notification cannot be restored. The list answers with total, everything you keep, because it returns at most limit items (50 by default, 500 at most); the panel loads more on request. A delete answers with the number removed in deleted and the unread count left. You can only ever remove your own notifications.

Events are live only. A client that was away lists the inbox. In a cluster, a notification added on one frontend reaches the clients connected to any other. When notifications are read or deleted, the stream sends a notifications_changed event, so your other open tabs read the list again and their unread badge follows. The notifications are rows in the shared database, so clearing the inbox on one frontend clears it for all of them.

Browser notifications

The inbox page can ask the browser for permission and subscribe it to push. A notification is then pushed to that browser, with its title and link and nothing else, also when no LocalAI tab is open. Clicking it opens the chat.

curl .../api/chats/push/key                       # the server's VAPID public key
curl -X POST .../api/chats/push/subscribe -d '{"endpoint": "https://...", "keys": {"p256dh": "...", "auth": "..."}}'
curl -X DELETE .../api/chats/push/subscribe -d '{"endpoint": "https://..."}'

• The server makes its VAPID key pair the first time it is needed and keeps it with the subscriptions: in the database, or in push.json (mode 0600) under the data path. With neither, push is off and these routes answer 409.
• The endpoint must be an https address on the public internet. The server refuses private, loopback and link-local addresses, both when a browser subscribes and when it sends, and it does not follow redirects.
• You can have 10 subscribed browsers; the oldest go first. A subscription that the push service reports gone is removed.
• In a cluster, the frontend that stores a notification sends the push, so it is sent once.

Storage and clusters

Saved agents, triggers, runs, notifications and push subscriptions are stored beside your chats: in the database when there is one, in JSON files under the data path otherwise, and in memory when there is no data path (the page then says persistent features are off, and push is off). The JSON stores are for a single process.

A cluster needs PostgreSQL, as the chats do. This is how each part of the state behaves with several frontends:

State	Mode	How
Agents, triggers, runs, notifications, push subscriptions	Shared	Rows in the database. Any frontend reads and writes them.
What a chat of an agent with a folder may reach	Stateless	The folder and its mode are columns of the agent's row. The frontend or chat worker that runs a turn, a trigger run, a connector reply or an add-on call reads them, and the folder, from the stores each time. Nothing is cached, so an edit applies on every frontend from the next turn.
Which frontend runs the triggers	Single runner	The frontend that holds the advisory lock (KeyChatsTriggers) runs the Runner. When it stops, another takes the lock.
A due time or a file version	Shared	One unique row for each trigger and due key. Two frontends cannot start the same run.
Trigger proposals and changes asked for in a chat	Stateless	Rows in the trigger table. Each request reads and writes them in the database, so any frontend can show, apply or undo them. The answer to a change (apply, dismiss, undo) is a conditional update of its row: when two frontends answer the same change at once, one wins and the other answers 409, so a change is applied or undone once.
Quiet periods of waiting files, the memory of a run's own writes	Per leader	Kept by the Runner of the current leader. A new leader reads the change feed again from its saved position, which stays below the oldest waiting file, so a file that was waiting is found again.
Live notifications	Shared, live only	Sent over the message bus to every frontend, with the "read or deleted" signal. A client that missed one lists the inbox, which is the record.
The supervisor of a running run	Per instance	The frontend that started the run watches it. The leader also ends any run that nobody watches whose chat is over, so a run is not lost when its frontend dies.
Where the turn of a run runs	Stateless	On the frontend that started it, or on a chat worker when the frontends send unattended turns there. The turn claim, its heartbeat and the waiting messages are in the database, so either one can run it and only one does.

JSON storage

Without an auth database, persistent chats and agent definitions use per-instance JSON storage. These stores use in-process mutexes and atomic writes. Run one process per JSON directory on a local filesystem; clusters use the SQL stores. There is no cross-process directory lock or historical selection ledger. Status observations use current principal-scoped reads in either backend.