Chats

Chats are conversations that the server keeps. You can keep typing while the model works, the model can hand work to sub-agents, long conversations are compacted for you, and the model can use the MCP servers of its model configuration.

The chats API sits beside the OpenAI-compatible /v1/chat/completions endpoint, which does not change. Use /v1 when a client brings its own history and needs the OpenAI format. Use /api/chats when the server should keep the conversation.

Permissions

With authentication on, an administrator grants features to each user in Settings → Users and keys. Plain chats are on by default. The parts that run without a person, or reach the outside world, are off by default for a user, and an administrator always has all of them:

A command-line MCP server (stdio) in your MCP connectors stays for administrators only, whatever the features. A trigger or a connector whose owner loses its feature stops running: a trigger run is skipped with the reason, and the bot says it is not available. The owner can get the feature back without losing the definition.

Upgrading. On the first start after the features were split, a one-time rule keeps what each existing user was using, and nothing else. The rule runs once; a user who registers later gets the defaults. A value an administrator stored always wins.

• agents: kept if the user has the stored agents permission (the one the old agent pool had) or owns a saved agent.
• triggers: kept if the user owns a trigger, or had agents or mcp_jobs.
• connectors: kept if the user owns a connector binding, or had agents.
• mcp_jobs: stored as it was.

Items that the conversion of the old agents makes after that first start belong to users who had the old permissions, which the rule already read.

What an administrator can see

An administrator sees what every user has set up, each with its owner, and can stop it. The view is read-only apart from switch-off and delete, and never shows a bot token or an agent’s instructions:

The agent tasks and jobs have their own view: ?all_users=true on GET /api/agent/tasks and GET /api/agent/jobs (see Agent tasks and jobs).

Switch the chats off

The operator can switch the whole surface or one part off. A part that is off starts nothing: no loop, no trigger runner, no bot. GET /api/features reports what runs (chats, agents, triggers, connectors).

LOCALAI_DISABLE_COLLECTIONS stays separate and turns off only the collections.

Start a chat and send messages

# A chat talks to one model, chosen when it starts.
curl -s localhost:8080/api/chats \
  -H 'Content-Type: application/json' \
  -d '{"model": "my-model"}'
# {"id":"3f1c...","model":"my-model","running":false,...}

curl -s localhost:8080/api/chats/3f1c.../messages \
  -H 'Content-Type: application/json' \
  -d '{"text": "Summarize the three files I mentioned."}'
# {"started":true}

# Rename a chat. This answers 409 while a turn runs.
curl -s -X PATCH localhost:8080/api/chats/3f1c... \
  -H 'Content-Type: application/json' \
  -d '{"title": "Trip plans"}'

The reply is not in that response. Read it from the event stream or from the transcript:

# Live server-sent events: text, reasoning, tool_start, tool_end, turn_end, files, ...
curl -N localhost:8080/api/chats/3f1c.../events

# The transcript, in order. Read it first, then open the event stream: the
# stream carries only what happens after you connect.
curl -s 'localhost:8080/api/chats/3f1c.../messages?after=0'

# After a dropped connection, send the id of the last event you got.
curl -N 'localhost:8080/api/chats/3f1c.../events?after=9d2e41.57'

The events of a running turn have an id, <run>.<n>, sent as the SSE id field. A client that lost its connection sends the last id back in the after query parameter, or in the Last-Event-ID header (a browser sends that header when it reconnects by itself; the header wins). The server first sends the events it missed, then the live ones. Deltas of text and reasoning that came one after the other are not sent again, and the ones the client had are cut off. The server keeps the last 2048 events or 4 MiB of each running chat, and the ring stays for 30 seconds after the turn ends, so a client that reconnects at once also gets turn_end. Events that do not come from the turn itself (files, goal, dock, loops, cleared and the cards) have no id and are not replayed: they tell the client to read the record again.

When the server cannot give what was missed, the stream starts with a resync event. This happens when the id is of another turn, is older than the ring holds, or is not an id of this server, and in a cluster when the server that runs the turn is gone or does not answer in 2 seconds. Read the transcript, then go on: the resync event carries the id of the newest event known, when there is one, and the live events follow it. A gap in the numbers of the live events is filled from the ring in the same way.

A user can have 8 event streams open on one chat on one server; one more gets HTTP 429 until one closes. The counter localai_chat_event_resyncs_total counts the reconnects that got a resync, by reason: local (the ring of this server did not have the events), owner (the ring of the server that runs the turn did not have them), unreachable (that server did not answer) and no_owner (no other server is known to run the turn). A steady rate of local or owner says that the ring is too small for your clients’ gaps.

The transcript lists messages, tool lines and one checkpoint line per turn. Undo works per tool call, not per turn: each write_file, edit_file or move_file call is its own change set in your files, and its tool line carries a card {"kind": "files_change", "id": "<rev>:<path>"} (delete_file moves to the Trash, where you restore it). POST /api/chats/files/undo {"rev": N} undoes that change set; the chat page uses this for the Undo of its change notes (see Make LocalAI yours). To undo a whole turn, undo the changes of its tool lines, newest first. The checkpoint line marks the end of the turn; its rev is 0 and its text is empty, because the turn’s changes are already kept call by call.

A chat is named after the first line of its first message, unless you gave it a title. To rename it, see Settings, rename and model change.

Start a chat with its switches

A chat can start with tools, add-ons and skills already switched off, and with opt-in tools switched on. switches in POST /api/chats takes each list in the form its own endpoint takes (see Switch tools off for one chat and Skills). The chat is stored with them, so its first turn already has them. A bad entry refuses the whole request with 400, and no chat is created.

curl -s localhost:8080/api/chats -H 'Content-Type: application/json' -d '{
  "model": "my-model",
  "switches": {
    "addons_off": ["office"],
    "mcp_off": ["crm", "connector:c1"],
    "builtins_off": ["web"],
    "builtins_on": ["saved_agents"],
    "skills_off": ["addon:pdf"]
  }
}'

To show these switches before the chat exists, read what a chat on a model (and a saved agent of yours) could use. Each switch is in its default state:

curl -s 'localhost:8080/api/chats/draft/tools?model=my-model'
curl -s 'localhost:8080/api/chats/draft/addons?model=my-model&agent_id=<agent>'
curl -s localhost:8080/api/chats/skills

The answers have the shapes of GET /api/chats/{id}/tools and GET /api/chats/{id}/addons. A model you may not use is 403, a model the server does not have is 400, and another user’s agent is 404.

The draft add-ons list also takes the switches the composer has so far, as comma-separated query parameters addons_off, builtins_off and builtins_on (the lists that POST /api/chats takes in switches). The commands state of the answer is then the one the new chat would have: with builtins_off=shell it is switched_off. A name that is not an add-on switch or a built-in group is 400. The Home composer sends them each time you change a switch.

List the chats of one origin

GET /api/chats returns every chat unless you send origin. With origin=person it returns only the chats a person started, with origin=automated only the chats that something else started, and with an origin kind (trigger, connector, job, page) only the chats of that kind. Each chat carries origin (empty for a person) and origin_id (the trigger, binding, job or page that started it). With origin set, limit counts the chats kept and sub-agent runs are left out, so a burst of chats from a bot cannot push your own chats out of the first page.

curl -s 'localhost:8080/api/chats?kind=chat&origin=person&limit=8'
curl -s 'localhost:8080/api/chats?kind=chat&origin=automated&limit=200'

Keep typing while the model works

Send another message while a turn runs and it waits. The response says so:

{"started": false, "pending_id": "p2"}

Waiting messages reach the model together, in the order you sent them, at its next request. A waiting message shows the files you attached to it as the same chips a sent message has. Until it is delivered you can change or remove it:

curl -X PATCH  .../api/chats/3f1c.../pending/p2 -d '{"text": "Use euros."}'
curl -X DELETE .../api/chats/3f1c.../pending/p2

Once a message has reached the model, both calls answer 409. A pending_delivered event tells you when that happened.

If the turn ends normally before a waiting message was delivered, that message starts the next turn. After a stop or a failed turn, nothing starts by itself: the messages stay, and you decide.

curl -X POST .../api/chats/3f1c.../stop       # end the running turn
curl -X POST .../api/chats/3f1c.../send-now   # start a turn from the waiting messages

Talk to a chat (Live)

Live lets you talk to an open chat with your voice. You speak, the chat answers, and a voice reads the answer aloud. Then Live listens again. You do not press a key.

What you need:

• A microphone, and a page opened over HTTPS or from localhost. A browser gives microphone access only to those pages. On any other address the Live button is off and says why.
• One model for speech to text (for example whisper-base) and one model for the voice (for example kokoro-multi-lang-v1.0-sherpa).

Start Live with the Live button next to the message box of a chat. If a model is missing, the button opens a sheet that shows the missing parts. An administrator can install a small model for each part with one click. A user who is not an administrator sees the names of the models and must ask an administrator to install them. When both models are installed, press Start Live.

You can also press Live on the message box of Home. LocalAI creates a chat with the model, agent and settings you picked on Home, opens it, and starts Live there. If a model is missing, the chat opens with the setup sheet. The text you typed on Home stays on Home. If you end Live before you say anything, the empty chat stays in your chat list.

Your audio is sent to your LocalAI server. The server turns your speech into text and makes the voice. Your audio stays on the LocalAI instance, and the browser does not use a cloud speech service. The text of the chat goes to the chat model as in a typed chat, so it goes where that model runs.

The dock shows a Standard chip. In this mode Live does not listen while the voice speaks. You cannot interrupt the voice, and the voice cannot hear itself. To cut the voice short, press Stop. Live then listens again. Live is half-duplex per browser tab, so use Live in one tab per chat.

Live uses the same chat, not a separate one. Your words appear in the thread as normal messages. Tools, history, files and the settings of the chat work as in a typed chat. A turn that fails is not read aloud, and Live listens again. Esc and the Stop button of the message bar stop a running turn and keep Live on. When the turn is one you started by voice, the part of the reply that was already written is not read aloud, and Live listens again.

Other controls: Mute and Unmute the microphone, Type instead (ends Live and puts the cursor in the message box) and End Live. Live pauses while the browser tab is hidden. If the browser blocks the audio (some browsers allow sound only after a click), the dock shows a Play button. Press it to hear the answer.

Loops: repeat a prompt in a chat

A loop sends a prompt to its chat again and again, as a new message, until you stop it. Type /loop in the message box, or use the API.

/loop 5m Check the build and tell me when it is green.   every 5 minutes
/loop Watch the deploy and tell me when it is done.      self-paced
/loop list                                               the loops of this chat
/loop stop                                               stop every loop of this chat
/loop stop 3f9a01                                        stop one loop (the code that /loop list shows)

• With an interval (30s, 5m, 2h, 1h30m) the prompt is sent at each interval. The shortest interval is one minute unless an administrator changes it (chats_loop_min_interval, never below 30 seconds); the longest is 24 hours.
• Without an interval the loop is self-paced: after each run the model calls schedule_next with how long to wait (from the minimum interval to 24 hours) and a short reason, or loop_done when the task is complete. A run in which the model calls neither ends the loop with a note, so a loop never goes on silently. The chat has these two tools only while it has a self-paced loop.
• Started by the model. A chat without a self-paced loop gives the model the start_loop tool. When the model tells you that it will check, wait or retry later, it calls start_loop with the prompt of each run, how long to wait before the first run (first_run_after, such as 2m) and a short reason. The loop starts at once and does not ask you first. You see it as a line above the message box with the reason, and you can pause or stop it. The limits below apply: the minimum wait, the loops per chat and per user, and the run limit. The tool is offered in your chats, in chats of a saved agent (whatever tools the agent allows), in sub-agent chats, and in chats that a trigger, a job or a page started. It is not offered when loops are off. In a chat that a connector started (Telegram, Slack and so on), the sender can be someone from outside, so the tools follow the access model of the bot: start_loop, schedule_next and loop_done need the capability loops.start and a verified (paired) sender, and wait_for and wait_agents need the capability loops.wait and a listed or paired sender. loops.wait is on by default for new bots and is added once to existing bots; loops.start is off until the owner ticks it, as for any other capability (see Chat apps and connections). A bot that accepts anyone gives neither to a sender who is not paired. The server checks the capability again when the model calls the tool. A loop in a chat that a trigger, a job, a page or a connector started ends after a fifth of the run limit (20 runs by default). The runs of a loop have no sender, so a connector chat keeps schedule_next and loop_done while its loop runs.
• Sub-agents. A sub-agent can start a loop, end its turn and wait. The parent is not told that the sub-agent finished until its loop ends: by loop_done, the run limit, a pause after failed runs, or a stop. Then the parent gets the last result. Meanwhile the sub-agent shows as running, and it counts once against the limit of background sub-agents. Stopping the parent or the sub-agent ends the loop. You cannot start a loop in a sub-agent chat yourself.
• Waits: wait_for. A model that says “I will wait until the download is done” can arm a wait. A wait is a loop whose check is code, not a model call: the server polls a source and calls the model once. The source is a read-only tool of the same chat with fixed arguments (for example a tool that lists downloads; the chat must be allowed to call it, and only tools whose name says they read, such as list_*, get_*, search_* or *_status, can be polled), a URL, which is read like web_fetch and so passes the same checks, a script, a shell command that the server runs for each check (see below), or a job, a background job of the same chat (see “Waits on a job”). The condition is change (the output differs from the first check), match (a regular expression), json_equals (a JSON field equals a value) or, for a script only, exit_zero (the command exits with status 0). For a job only, exit and stall apply. The first check sets a baseline and never wakes the model (a job has no baseline); an error is not a change. The model wakes when the condition holds, when the source fails max_errors checks in a row (3 by default), or at the timeout (timeout_seconds; 1 hour by default, 24 hours at most). Failure and timeout wake it too, and the wake-up text says plainly that the condition was not met. The check interval (interval_seconds) is at least the loop minimum. The tool is nib’s own wait_for, answered by the server. A wait is listed with the loops (the API gives it kind: "wait"), counts against the same limits, and you stop it like a loop. A sub-agent that arms a wait stays running until it ends, as with a loop.
• Waits on a script. With script, the server runs the command for each check and the model is not called. The command runs where the chat’s bash runs: in the Sandbox add-on when one serves the chat, otherwise in the built-in bash on the server. It has the same fixed environment, the same 120 second timeout and about the same 64 KiB output limit as bash, and its output is the standard output and standard error together. The rules:
  • A non-zero exit status is a result, not a failure. The exit status and the output feed change, match, json_equals and exit_zero; a status that changes is a change even when the output does not. Only a command that does not finish in time, or that cannot be run, counts toward max_errors. For json_equals, the output of a command that failed is read as “not there yet”, not as a failed check.
  • A check changes no file. It runs read-only: what the command writes is not saved to your files and makes no change set. It can read your files.
  • Arming it needs a chat that can run commands. wait_for refuses a script when the chat has no bash: bash is switched off for the chat or by an administrator, the Shell tool group is off, the server cannot run commands and no Sandbox serves the chat, the files are off, the agent works in one folder (only the Sandbox can serve that), or the chat is an unattended run without an agent. A sub-agent cannot arm a wait on a script. In a connector chat the sender needs the loops.wait capability, as for other waits.
  • In the mode ask for the built-in bash, only an administrator can arm a script wait. The administrator allows the whole command once, in a card, when the wait is armed; a command over 2000 bytes is refused. The checks then run with no card. A command that the Sandbox runs needs no card.
  • The command is shown to you in the chat, not in the list. The answer of wait_for contains the command, and the model is told to show it to you. The loops list, its API and the interface name the source script and show a generic line; the command is kept only in the store of the owner.
  • Budget. Checks of scripts have their own daily budget per user, apart from the 200 model runs: 1500 checks a day (UTC), over all the user’s waits. A check is charged before it runs. When the budget is used up, the wait ends and the model is woken with a text that says the condition is not known. A wait still ends after 2000 checks, and the limits per chat and per user still apply.
  • If the server cannot run the script at a check (the server lost its host exec, or the Sandbox no longer serves the chat), the wait ends at once and the model is woken with a text that says plainly that the script cannot run on this node and was not run. The wait is not pinned to a node.
• Waits on a job. With job, the server reads a background job of the same chat that job start returned. A check is a read of the job’s memory on the node that runs it: it starts no process, spends no script budget, asks for no approval and never shows a command. The conditions are:
  • exit (the default for a job): the job has ended, with any status. The wake-up gives the exit status, how long it ran and the last 2000 bytes of its output. A non-zero status is stated, never hidden.
  • stall, with idle seconds (60 to 3600, default 600): the job still runs but wrote no output for that long. The wake-up says it may wait for input, hang or work quietly, and gives the tail. A job that has already exited wakes the wait as exited, never as stalled.
  • match: a regular expression over the output the job wrote, read in order from the first byte and once each, at every check. A match that falls across two checks is missed. When the job exits and its output never matched, the wait ends with a plain text that says so and that the condition was not met.
  • change and json_equals are refused for a job: it has no output to compare. A job that has already ended is not armed (read it with job read). A job of a sub-agent is waited for by the sub-agent. When the job ends, the wait is checked at the next tick of the loop host (about 5 seconds) instead of at the next interval. A check that cannot reach the node that runs the job changes nothing and counts as a failed check (max_errors); a job that the node does not know ends the wait at once, with a text that says the job is gone with its node, that its output and exit status are lost, and that the condition was not met. A wait on a job is pinned to the node that runs the job, which it records when it is armed. The loops list and its API name the source job with the id and the label, and never the command.
• Tools of a sub-agent. The names of the tools the parent gave a sub-agent are stored with its chat. After a restart, or when another frontend runs its next loop run, the sub-agent gets back those tools, limited to what the parent may use at that time: it never gains a tool, and a tool that is gone is removed with a short note to the model.
• Waiting for sub-agents: wait_agents. A chat that started background sub-agents can wait for them with ids (empty: all that run now) and a mode, all or any_failed_or_all. The wait is bounded by timeout_seconds (30 seconds by default, from 10 seconds to 10 minutes); at the timeout the tool returns the current statuses and the sub-agents keep running. An unknown id is reported at once. spawn_agent with wait set to true returns after at most two minutes of waiting for a sub-agent that ended its turn and holds for a loop or a wait; the sub-agent then goes on in the background and its result arrives as a message. To be woken when a background sub-agent makes no progress, wait_for takes the id that spawn_agent returned as job, with exit or stall (see “Waits on a job” and “Background jobs”).
• The promise guard. When the last answer of a turn promises a later check or action (“I’ll check in a few minutes”, “Controllo tra poco”) and nothing is armed in the chat (no active or running loop or wait, no running sub-agent, no queued message), the server adds one short note for the model and the model gets one more turn: arm a loop, a wait or a background sub-agent now, or tell you plainly that it cannot watch. It happens at most once per turn. In a chat that a connector started, the note names only the tools that the sender may use (see above); with none, it only asks the model to say so plainly. Sub-agent reports are not checked. The matcher reads English, Italian, Spanish, French and German and ignores questions, offers and promises that wait for you.
• The prompt is plain text, or a skill: /<skill-name> (or /skill <name>) and its words. Each run sends it as that skill command would: the transcript shows the words and the skill’s chip. Other slash commands cannot repeat. A skill that is gone or switched off at a run makes that run fail.
• The first time in a chat a card asks Run this every 5 minutes until you stop it? with Start and Cancel, because every run costs tokens. The card stays with the chat, so it is still there after a reload. Once you start one loop in a chat, later loops there start at once.
• What you see. Each loop shows as a line above the message box, such as Loop · every 5 min · run 4, with Pause and Stop. A message that a loop sent has a small Loop run 4 label, so you can tell it from one you typed. A loop that ended by itself stays as a line with the reason until you dismiss it.
• Busy chats. A run starts only when the chat is idle. When you or another run keeps the chat busy at the due time, that run is skipped, and the loop waits for its next interval instead of piling runs up. A self-paced loop runs as soon as the chat is free.
• Limits. A chat has at most 3 loops and a user at most 10 (chats_loop_max_per_chat, chats_loop_max_per_user; ended loops do not count). A loop ends after 100 runs (chats_loop_max_runs). One user starts at most 200 loop runs a day, over all loops (chats_loop_daily_runs, UTC days); after that the loops wait for the next day. Checks of waits on a script have a separate budget of 1500 a day per user. A loop pauses itself after 3 failed runs in a row; Resume starts it again. A run has a time limit of 15 minutes.
• Stop removes a loop. It does not stop a run that goes on; the chat’s stop button does that. Deleting a chat removes its loops.

# Start a loop (no interval: self-paced). The first loop of a chat is pending.
curl -X POST .../api/chats/3f1c.../loops -d '{"interval": "5m", "prompt": "Check the build."}'
# {"id":"9b2e...","prompt":"Check the build.","interval":"5m","interval_seconds":300,
#  "state":"pending","runs":0,"running":false,"created":"..."}

# Confirm it (state active), pause it, or resume it.
curl -X PUT .../api/chats/3f1c.../loops/9b2e... -d '{"state": "active"}'
curl -X PUT .../api/chats/3f1c.../loops/9b2e... -d '{"state": "paused"}'

# List, stop one, stop all.
curl .../api/chats/3f1c.../loops
curl -X DELETE .../api/chats/3f1c.../loops/9b2e...
curl -X DELETE .../api/chats/3f1c.../loops

A loop’s state is pending (waits for your yes), active, paused or ended; reason says why it paused, ended or waits, next when it runs next, and wait what the model of a self-paced loop waits for. GET /api/chats/{id} carries the same list as loops, a loops event tells every open tab that the list changed, and a user line that a loop sent carries loop: {id, run} in the transcript.

Loop or trigger?

Both run a prompt without you typing it. Choose by where the answers should go and how often:

In a cluster. State mode: single-runner. The loops live in the shared store with the chats (the auth database). One frontend at a time fires them: the one that holds a PostgreSQL advisory lock, as for triggers. A run is claimed in the store before it starts, and the turn claim of the chat keeps one turn per chat, so two frontends never start the same run. After a restart, or when another frontend takes over, the loops go on from the store, and a run that a dead frontend left behind is finished and counted as failed. A loop run starts on the frontend that fires it; it is not sent to a chat worker.

Settings, rename and model change

A chat keeps its own model settings. They apply from the next turn, and they are part of the chat: a fork and an export carry them.

curl -X PATCH .../api/chats/3f1c... -H 'Content-Type: application/json' -d '{
  "title": "Trip plan",
  "model": "another-model",
  "settings": {"system_prompt": "Answer in short sentences.", "temperature": 0.3,
               "top_p": 0.9, "top_k": 40, "reasoning_effort": "low", "context_size": 16384}
}'

• system_prompt goes before the instructions of a saved agent.
• temperature (0 to 2), top_p (above 0, at most 1), top_k and reasoning_effort (none, minimal, low, medium, high) go to the model with every request of the chat. A missing field means the model’s own default. settings replaces all of them, so send the whole object; {} clears it.
• context_size is the window, in tokens, that the loop plans with when it decides to compact the conversation. It does not reload the model and does not change the window the backend loads, so it cannot make a small model large enough; only the model’s own context_size does that.
• A new title (1 to 80 characters) or model needs a chat with no turn running (409 otherwise). The history stays when the model changes.

In the web UI, the Effort chip in the message box (next to Tools and Skills, on the chat page and on the Home page) and the chat settings sheet (/settings, or the sliders icon in the chat header) show and change the same reasoning_effort. The chip and the effort buttons in the sheet apply at once. In the sheet, temperature, top P and top K are sliders with a number box and a reset button; an empty value means the model’s own default. The sliders cover 0 to 2 (temperature), above 0 to 1 (top P) and 0 to 200 (top K). You can type a larger top K in the box. These values and the system prompt and context size are sent when you press Save settings. reasoning_effort none asks the model not to think.

A level picked on the Home page is saved to the new chat when it is created, before the first message is sent, and the chat page opens with it.

Context meter and speed

Each model request sends a usage event with used (tokens in the context the request sent), limit (the window the loop plans with, when known), completion (tokens generated), tokens_per_second and prompt_ms (the time the backend took to read the prompt; both only when the backend reports timings), model (the model of the request) and node (the worker that served it, only when the server runs with --expose-node-header).

The status line

The line under the composer shows what the chat is doing now, as one word: Ready, Loading model, Thinking, a tool step (for example Reading q2.pdf), Answering, Waiting for you (messages wait for Send now), Paused, Stopped, Failed or Interrupted. A spinner marks a running turn, and an icon marks a state that needs your attention. While the composer has focus and is empty, the line also shows the keyboard hint.

Paused means that the turn used all its steps: the model made as many rounds of tool calls as one turn allows (chats_max_iterations, 40 by default) and then wrote an answer from what it had, so the work may not be finished. The line says how many steps the turn used (for example Paused · after 40 steps) and shows a Continue button. Continue sends a message that asks the model to go on from where it stopped; you can also type your own. A turn that pauses is otherwise like one that ended by itself: messages that wait start the next turn, and a sub-agent that pauses reports back. The API reports it as last_turn: "paused" and sends a paused event with steps before turn_end.

On the right, the context meter shows how full the model’s context was at the last request: a bar, the tokens used and the limit (for example 12.3k / 32.8k tokens), the tokens left (20.4k left) and the speed of that request. Two ticks on the bar mark 80 % and 90 %. While an answer streams, the speed is an estimate (shown with ≈); the measured figure replaces it when the request ends. From 80 % the meter turns amber, from 90 % red, both with a warning icon. When the server does not know the limit, the meter shows only the tokens used, with no bar. Where the line is narrow, the percentage replaces the used and limit figures; narrower still, the speed moves to the details. Select the meter to see:

• the context used, the limit and the tokens left, and what happens near the limit (the server compacts the older part of the chat),
• the model, its backend and, when the server runs with --expose-node-header, the node that served the request,
• the tokens in and out, the time to the first token, the prompt processing time and the speed, with the average of the last requests.

The figures come from the usage events of the page’s event stream. The server does not keep them, so they are empty after a reload until the next request. On a phone the line shows the word, the bar, the percentage and the tokens left, and the details open in a sheet.

Goals

A goal is an objective that a chat keeps working toward over many turns, for example “Turn the notes in /Research into a two-page summary and check every figure”. While a goal is active, the chat does not wait for you to say “continue”: when a turn ends by itself, the server starts the next one.

Set a goal with the /goal command in the composer, or with the API:

While the goal is active:

• Every turn’s instructions name the goal, and the model gets two tools: goal_done (the goal is reached, with a one-line summary) and goal_blocked (the model cannot go on without you, with the reason and what it needs). The tools exist only while a goal is active.
• When a turn ends by itself, the server sends the next turn Continue toward the goal: "<text>". The transcript shows it as a goal line, not as a message from you.
• Your messages still steer the work. A message you send while a turn runs reaches the model at its next step, and messages that wait run before the next automatic turn. Turns that you start do not count as automatic turns.
• Above the composer, a line shows the goal with Pause (or Resume) and Clear. The status line shows the progress, for example Goal · turn 3 of 20.

The goal has one of four states:

Two runtime settings in Settings > Tools limit a goal: chats_goal_max_turns (20 by default) is the most turns the server starts by itself for one goal, and chats_goal_max_steps (400 by default) is the most model steps that the turns of one goal make together. A goal that reaches a limit pauses, and resuming it starts new counts. The step limit of one turn (chats_max_iterations) still applies to each turn.

A goal belongs to a chat that you started. A sub-agent, and a chat that a trigger, a connector, a job or a page started, cannot have a goal and never gets the goal tools.

# Set a goal. With no turn running, a turn starts on it at once.
curl -X PUT http://localhost:8080/api/chats/$ID/goal \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Turn the notes in /Research into a two-page summary"}'
# {"goal":{"text":"Turn the notes in /Research into a two-page summary","state":"active",
#  "turns":0,"max_turns":20,"steps":0,"max_steps":400,"set":"...","updated":"..."}}

# Read it. GET /api/chats/$ID also carries it as "goal".
curl http://localhost:8080/api/chats/$ID/goal -H "Authorization: Bearer $KEY"

# Pause it (Stop pauses the goal), resume it, clear it.
curl -X POST http://localhost:8080/api/chats/$ID/stop -H "Authorization: Bearer $KEY"
curl -X POST http://localhost:8080/api/chats/$ID/goal/resume -H "Authorization: Bearer $KEY"
curl -X DELETE http://localhost:8080/api/chats/$ID/goal -H "Authorization: Bearer $KEY"

A paused goal has paused_by: user, turn_limit, step_limit, error or interrupted. A done goal has the model’s summary in note, and a blocked goal has its reason there. The event stream sends a goal event when the goal changes (its text is the new state, empty when the goal was cleared), so every open tab reads the chat again. The transcript has goal lines with role goal and goal_event set to set, replaced, continue (with goal_turn), paused, resumed, done, blocked or cleared. Goal lines are not exported and not copied by a fork.

Several frontends. The goal is stored with the chat record in the shared store, so every frontend reads the same goal and nothing about it is kept in memory. The next turn of a goal goes through the same per-chat turn claim as any other turn: only the frontend that ran the turn starts the next one, and a message from you, or a resume on another frontend, never starts a second turn. If a frontend stops during a turn, the turn is reaped as interrupted and the goal pauses, so a restart never continues a goal twice.

Regenerate, edit, fork, search, export

# Answer the last message again. Your messages of that turn stay.
curl -X POST .../api/chats/3f1c.../regenerate
# Replace one of your messages and run the chat again from it. The messages
# after it are removed. seq is the line number in the transcript.
curl -X POST .../api/chats/3f1c.../messages/12/edit -d '{"text":"A better question"}'
# Copy the chat up to and including line 14 into a new chat.
curl -X POST .../api/chats/3f1c.../fork -d '{"from_seq":14,"title":"Other idea"}'
# Find chats by title or by what was said, in all your chats.
curl '.../api/chats/search?q=invoice'
# Take a chat out as Markdown (default) or JSON, and bring a JSON file back in.
curl '.../api/chats/3f1c.../export?format=json' > chat.json
curl -X POST .../api/chats/import -d "{\"chat\": $(cat chat.json)}"

• Regenerate and edit remove the lines after the cut point from the transcript and from what the model sees. Files that the removed turns changed stay changed, and tool calls of the kept part are not replayed to the model, only the messages.
• A fork has the model, the settings and the tool switches of the original. It has no folder and no files of its own until you attach some.
• The JSON export has version, title, model, settings and messages (role, text, at, and for a message of yours with files attachments, with the path of each file, and note, the text the model read from them). It holds no files and no model state. The Markdown export and a copied chat name the files of a message, not their paths. An import makes a new chat of yours with the model of the file, or the one named in model, which you must be allowed to use.

Search your chats

GET /api/chats/search?q=... searches the titles and the messages (yours and the model’s) of all your chats. It does not search the runs of sub-agents, and it never returns a chat of another user.

• Words and phrases. A message matches when it holds every word of q, in any order, as part of a word or whole. A phrase in double quotes counts as one word: q="port of qdrant". The search ignores case.
• Ranking. The best match comes first: a message with the whole phrase or with whole words ranks above one with word parts, and newer messages rank above older ones. A search ranks the newest 600 matching messages.
• One hit for each chat. A hit carries chat (with the agent and the origin), seq (the line of the message), role, at, a snippet and highlights: the parts of the snippet that match, as start and end offsets in UTF-16 units, so a client can mark them without parsing HTML. Add group=message to get every matching line.
• Filters. agent (a saved agent), origin (person, automated, trigger, connector, job or page), role (user or assistant), since and until (a date YYYY-MM-DD or an RFC 3339 time; a date in until includes that whole day) and limit (default 50, at most 200).
• In the web UI. The search box of the Chats page and of the Ctrl or Cmd+K dialog uses this search. From two characters it lists the hits best first, each with the chat, who wrote the line, its date and a snippet with the matched words marked. Three filters (agent, source, date) narrow it, and Reset filters takes them off. Arrow keys move through the hits, Enter opens one, and Escape clears the search first and closes the dialog next. A hit opens its chat at the message: the address /app/chats/<id>?seq=14 scrolls to line 14 and marks it for a moment. The list says when it is still searching, when nothing matches, when the search failed (with Try again), and when older chats are still being indexed.
• After an upgrade. The server keeps a search index. When it starts with chats from before the index, it adds them in the background and logs the progress; the answer says indexing: true until that ends, and older chats can be missing meanwhile. The index uses SQLite FTS5 (trigram), or pg_trgm on PostgreSQL; without them the server scans. Deleting a chat, or regenerating or editing from a message, removes the old text from the index in the same step.
• Chats in files. A server that keeps chats in files (no database) has no index. It scans the newest chats first for up to two seconds and sets partial: true with searched_chats and total_chats when it stopped early.

Images, video and documents

Attach files with multipart/form-data on POST /api/chats/{id}/messages (see above). In the chat page, one Attach file button takes files of any type (images, audio, documents, archives such as .zip); you can also paste an image, or drag files over the page and drop them. The same works on Home. A drag of text is ignored, and with files off nothing is staged. What the model gets depends on the file and the model:

• Images. When the chat’s model can look at images (a multimodal projector, vision in known_usecases, or image in known_input_modalities) the image goes to the model inside the message, as an image_url part, and the model answers about it directly. A model behind a cloud proxy cannot be asked what it accepts: declare vision in its configuration (see Cloud passthrough proxy). With a model that cannot look at images, the model gets the file path and the describe_image tool.
• Video. mp4, webm, mov, mkv and avi files go to a model that declares video input as a video_url part, with the next request after the message and for that turn only. Other models get the path only.
• PDF, Word, Excel, PowerPoint and EPUB. The text of the file is added to the message, the first 20,000 characters of each document, and the model reads the rest with the read_document tool (offset and limit). No helper model is needed. A workbook (.xlsx, .xlsm) comes sheet by sheet, each sheet as a heading and its rows as tab-separated lines, up to 2,000 rows and 50 columns per sheet; a note says what a cut sheet leaves out. A Word document gives its headings (#), list items, paragraphs and tables (one tab-separated line per row), and a presentation its slides, each with its title, text and speaker notes. A PDF with no text layer is reported as a probable scan; an Office file with no text is reported as empty.
• Audio. A voice note is transcribed when a transcription model is set, as before.

The files are always kept in the chat’s folder too. Images over 20 MB, videos over 100 MB and more than 128 MB of media in one message stay files only.

Images and vision

• Size. An image whose longest side is more than 2048 pixels is scaled down to 2048 before it goes in the message. An opaque image goes as a JPEG, an image with transparency as a PNG. The file in the chat’s folder is not changed.
• Only with its own message. The images of a message go to the model with every request of that turn, tool calls included. The next messages do not send them again: in the history, each earlier image becomes a short note that says so. To look at an earlier image again, the model uses describe_image on its file. This keeps a few photos from filling the context, and a cloud model from billing them on every turn.
• What the model is told. A chat with files gets an Images: block in its instructions, after the Commands: block. It says that the model sees the attached images and answers about them directly, or that it cannot see images and uses describe_image, or that no model here can look at images: then the model tells the user so and suggests choosing a model that can.
• describe_image. The tool uses the first model of this list: the Chat image model setting, the chat’s own model when it can look at images, the first installed model that can, and last the chat’s own model when it is a passthrough cloud-proxy model with no vision declaration. LocalAI cannot ask such an upstream what it accepts, so the tool tries it. If the model refuses the image, the tool says that the model did not accept it and what to do: turn on “This model can look at images” in the model’s settings, choose another model, or ask an administrator to set a Chat image model. A local model that cannot look at images is not tried. With no model to try, it fails with “No vision model: choose a model that can look at images for this chat, or an administrator can install one from the model gallery and choose it in Settings under Chat image model.”
• In the chat page. When you attach an image and the chat’s model cannot look at it, a notice over the message box says so and names the model that will describe the image, or says that no model can. GET /api/chats returns that model as image_model; the field is left out when there is none.

The files of a chat

Each chat lists the files that belong to it: the files you attached, the files the model created, and the files it changed. The model gets the list in front of your message whenever it changed since the model last read it, so it knows which files exist and where they are now. The list is not in the system prompt: it changes at most turns that write a file, and a changed system prompt makes a backend with a prompt cache read the whole conversation again.

• Where attachments live. In the chat’s own folder in your files: /Chats/<date>-<title slug>/<name>, for example /Chats/2026-10-29-budget/q1.csv. The name is the creation date and the title in lowercase ASCII letters and digits joined by dashes (accents are dropped; a character with no ASCII form, such as a middle dot, becomes a dash), so it never holds a space or a character that a shell would split or mangle. A title with no ASCII letter or digit gives new-chat. When two chats get the same name, the second gets -2, then -3. The model sees the same file as /workspace/home/Chats/2026-10-29-budget/q1.csv. A chat made before this form keeps its folder, such as /Chats/2026-10-29 Budget/, and that folder is not renamed when the title changes. The folder is made at the first attachment. In a chat whose agent works in one folder, the model sees the chat folder at /workspace/chat instead (the file above is /workspace/chat/q1.csv), and the folder is made before the first turn. The list on this page keeps the paths in your home.
• What is listed. Every file in the chat folder, and every file that the chat’s turns created or changed elsewhere in your home folder: with bash, or with a file tool such as write_file. The list is read from the history of your files, so a file that you or the model moved or deleted later is not listed at its old path.
• Rename. Renaming a chat renames its folder to match the new title (the new slug), and the list gives the new paths at once. A folder in the old form (<date> <title>, with a space) is left where it is. Earlier messages keep the old paths. The model is told at its next turn that the folder was renamed and which path is current.
• Delete. Deleting a chat removes its transcript and its sandbox. Its folder (with its work folder) and every file the model wrote stay in your files.
• Fork. A fork has no folder of its own until you attach a file. The files that the copied messages attached stay in the original chat’s folder; the fork lists them while they are there.

To follow the changes to your files as they happen (from any tab, chat, trigger or frontend), open the change feed (GET /api/workspace/events).

curl .../api/chats/3f1c.../files
# {"files":[{"name":"q1.csv","path":"/Chats/2026-10-29-budget/q1.csv",
#   "guest_path":"/workspace/home/Chats/2026-10-29-budget/q1.csv","size":2048,
#   "mime":"text/csv","origin":"user","turn":1,"at":"..."},
#  {"name":"report.md","path":"/report.md","guest_path":"/workspace/home/report.md",
#   "size":930,"mime":"text/markdown","origin":"model","turn":2,"at":"..."}],
#  "folder":"/workspace/home/Chats/2026-10-29-budget/","folder_path":"/Chats/2026-10-29-budget"}

origin is user (you attached it, or put it in the chat folder), model (a command of the model wrote it) or tool (a tool of the chat wrote it, such as write_file). changed marks a file the chat changed but did not create. media marks an attachment that the model received as an image or a video inside the message; the others reach the model by path. path works with the files API above. stale lists old folder paths that earlier messages name. A files event on the chat’s event stream says that the list may have changed; read it again.

Files that a command saved

A command of bash (the Sandbox’s, or the built-in one on this machine) saves what it writes in your home folder as one change of the chat, the same way write_file does. The chat then shows those files where it shows a file tool’s:

• Under the step. The bash step lists the files the command created or changed (“Saved to your files”), one chip each; a chip opens the file in the preview pane. A file the command deleted is listed by name, struck out.
• In the pane and under the answer. The files are in the chat’s file list above, with the turn that made them, so they get a chip under the answer and the preview pane opens by itself on the newest one (a Word, Excel, PowerPoint or PDF file, an image or a text file), as it does for a file of write_file.
• In the transcript. The tool line of the call has a card with files: [{"path":"/report.docx","rev":42,"op":"created"}], where path is inside your home, rev is the change set (undo it with POST /api/chats/files/undo) and op is created, changed or deleted. At most 50 are listed; files_more counts the rest. The card keeps its own kind and id (who served the call: tool_provider for the Sandbox, host_exec for this machine).

Only what the command saves under /workspace/home (or a writable shared folder) is kept. bash starts in the chat’s work folder and has its path in $WORK, so a relative path such as report.docx is in that folder (a chat with no work folder yet starts in /workspace/home, with no $WORK). A file written anywhere else, such as /workspace/report.docx or /tmp, is not saved, and the result of the call says so by name. When you or a file tool changed a file while the command ran, your version stays and the command’s version is saved as a copy; the result names the copy’s path.

The list of files comes from the change sets of the chat in the shared store, read after each call, so every frontend of a cluster shows the same files. Nothing about it is kept in memory.

The list that the model gets has the newest 50 files, one line each with the path, size, type, origin and turn, and a count of the rest. A chat with no files gets no list. The list is built from the stored history when a turn starts, so every frontend of a cluster gives the same one.

Working files and the work folder

A chat that makes a document often writes a script, some intermediate data or a log on the way. These working files must not mix with your own files, so every chat has a work folder: /Chats/<date>-<title slug>/work/ in your files (/workspace/home/Chats/<date>-<title slug>/work/ for the model), next to the chat’s attachments. It is a normal, visible folder.

• Where a command starts. Every shell of the chat starts in the work folder, and $WORK holds its path: the bash of the Sandbox, the bash on this machine and the background jobs of both. The folder is made before the shell starts. A chat with no work folder yet (or with the steering off) starts in /workspace/home, as before, and has no $WORK. The model can still write anywhere in your files: nothing restricts where a command writes. On this machine $WORK is a path of the scratch folder, not of /workspace.
• What the model is told. At every turn the note in front of your message names the chat’s work folder (the file tools take that path), says that the shell starts there and that $WORK holds it, and gives the quoting rule: use $WORK or relative paths instead of typing absolute paths, quote every path with double quotes, and never type out a name with spaces or non-ASCII characters but take it from ls or a glob. The prompt says: scripts, helper code, intermediate data, logs, drafts and anything else you did not ask for go there; the file you asked for (the document, the spreadsheet, the image) goes where you said, or at the top of your home, and nowhere else; no new top-level folders for scripts; a command that runs once needs no file (python3 -c, a heredoc). The descriptions of bash and write_file and the Sandbox document skills say the same. The built-in localai-apps and localai-workspace skills also give this guidance. Pages (pages/<name>/) and the LocalAI/ settings folder are not working files. The folder is named in the note and not in the prompt because its name carries the chat’s title: the prompt stays the same for every chat, so a backend with a prompt cache (llama.cpp) reuses it, with the tool definitions after it, instead of reading it again for each new chat.
• When the folder is made. The chat takes the name of its folder at its first turn, but makes the folder only when it is used: before a bash command runs, or when a file is saved there. A chat that saves nothing leaves no folder behind.
• A gentle nudge, no refusal. When write_file, move_file or a command leaves a helper file (see below) outside the work folder, its result gets one line that suggests moving it there, at most once a turn. Nothing is refused or moved: you may have asked for that script.
• Delete. Deleting a chat keeps its folder, with the work folder and the attachments in it, like every other file the chat wrote.

Each file of the chat’s list has a kind: deliverable or working. A file is working when it is in the work folder of any chat (/Chats/<chat>/work/...), or when it looks like a helper: the extension .py, .sh, .js, .ts, .mjs, .rb, .pl, .ps1, .bat, .log or .tmp, or a folder named scripts, tmp or scratch on its path. Files of a page, of the LocalAI/ folder or of a shared folder, and the files you attached, are always deliverable. The server decides the kind in one place and puts it on the file list (kind), on the files of a command’s card (files[].kind) and on the card of a file tool (file_kind).

curl .../api/chats/3f1c.../files
# {"files":[{"name":"summary.docx","path":"/summary.docx","kind":"deliverable",...},
#  {"name":"build_document.py","path":"/Chats/2026-10-31-summary/work/build_document.py",
#   "kind":"working",...}], ...}

In the chat:

• The Files pane opens from the Files button in the chat header, next to Dock, which shows how many files the chat holds. It shares the right side with the dock, so opening one hides the other. It lists what the chat made for you first. The working files are in a group of their own under it, Working files · N, folded and quieter; open it to see and preview them. The files you attached are listed as before. Download all files as ZIP, at the top of the pane, saves every file of the list, working files included, in one ZIP with the folder layout kept. It is off when the list is empty.
• The preview that opens by itself after a turn shows the newest file that is not a working file. A working file never opens it by itself.
• The chips under the answer name only what the chat made for you.
• A step that saved working files says so in one line (“Also saved 2 working files”); click it to see their chips.

An administrator can turn the steering off with Work folder for helper files (chats_work_folder, Settings > Tools). The prompt then names no work folder and no nudge is added; the pane still shows working files apart. The nudge is counted per process: a turn runs on one process, so nothing is shared, and a restart only lets the line come once more.

Sub-agents

The model can start a sub-agent for a self-contained task. By default it waits for the answer. With wait set to false it carries on, and the result arrives later as a message in the conversation and as a sub_agent_done event.

• A sub-agent is its own conversation, linked to its parent. It appears in the list with kind set to subagent and a parent_id.
• A sub-agent gets the parent’s tools, or a subset the parent names. It cannot start sub-agents of its own.
• A chat runs at most four sub-agents in the background at once. The count comes from the shared store, so it holds when turns of the same chat run on different frontends of a cluster.
• Stopping a chat, or a turn that fails, stops its running sub-agents, also when they run on another frontend and when the parent has no turn left.
• A sub_agent_started event (with the run’s id and title) and a sub_agent_done event mark the run in the parent’s event stream.
• A sub-agent of a chat whose agent works in one folder works inside the chat’s folders, never in more of your files and never with more rights than the chat.
• A sub-agent cannot run commands when its parent cannot (see Running commands). A task that asks to run something (“execute the script”, “run make_deck.py”) is then refused at once with “the sub-agent has no way to run commands either”, and no sub-agent starts.
• A task with the same words as an earlier sub-agent of the chat is refused while no file of the chat was created or changed since that run: it would answer the same. The check reads the store, so it holds on every frontend of a cluster.

curl .../api/chats/3f1c.../agents                      # runs, their state, the limit
curl .../api/chats/3f1c.../agents/9ab2.../messages     # one run's transcript
curl -X POST .../api/chats/3f1c.../agents/9ab2.../stop # stop one run

Jobs and stall waits of sub-agents

• Waiting for a quiet sub-agent. wait_for takes the id of a background sub-agent in job, with until exit (the default) or stall and idle from 60 to 3600 seconds (default 600). Progress is a new row in the sub-agent’s transcript, read from the store, so the wait pins no node and works from any frontend. One long tool call counts as quiet until it ends. The wake-up gives the last row, or the state and the last answer of a sub-agent that finished; that wake-up is the report of the end, so the parent does not also get the “Sub-agent finished” message. match is refused. The loops list and its API name the source agent with the id of the sub-agent.
• Jobs of a sub-agent. A sub-agent has the job tool exactly when it has bash, under the same rules: a host job only when commands on this machine run with no card (mode on), a Sandbox job always, and the act policy of an unattended parent applies. The limits are the usual ones: 4 jobs per chat, 8 per user (the jobs of sub-agents count), 32 per node. The job belongs to the sub-agent’s chat. A job on this machine runs in the parent’s scratch folder, where the sub-agent’s bash runs; a Sandbox job runs in a sandbox of the sub-agent’s own chat.
• Jobs end with the sub-agent (reason agent_ended): when its run reaches the parent, when the parent or you stop it, and when the sub-agent’s chat or its parent is deleted. A sub-agent that ends its turn without a wait_for on its job ends the job; the tool description says so.
• Job waits. A sub-agent may arm wait_for on its own jobs (not on a script). The wait keeps the sub-agent running, so it counts against the limit of background sub-agents and the loop limits, and its wake-up is a turn of the sub-agent, not of the parent. The parent can wait for the sub-agent, not for its job.
• The parent’s view. job list of the parent also shows the jobs of its sub-agents, marked (sub-agent <id>). The parent can read and kill them, not write input.

Saved agents as sub-agents

A chat can also start one of your saved agents as a sub-agent. This is off for every chat until you switch Saved agents on in the chat’s Tools menu. The chat then has two more things:

• list_agents lists your saved agents: id, name, description and model, at most 100, and for an agent that works in a folder the folder’s name (folder) and its mode (folder_mode, read or write). It lists only your own agents. In a chat whose agent has a folder it lists only the agents that can start there (see Folders of an agent).
• spawn_agent takes an agent argument, the id or the name (ignoring case) of one of them. The sub-agent runs with the agent’s instructions, its model (or the chat’s model when the agent names none) and only what the agent grants, the same as a chat started with that agent. tools cannot be given together with agent. The run is listed with the other sub-agents, with the agent’s name in its title.

The sub-agent cannot start sub-agents of its own and never gets list_agents. Each call checks again that the chat has the switch on, that an administrator left chats_saved_agents on, and that you have the agents feature, as the agents API does. When one of them fails, or the agent does not exist or is another user’s, the call fails with a message that says why and no sub-agent starts. Without the agents feature the switch is shown greyed out with the reason.

curl -s -X PUT localhost:8080/api/chats/$ID/builtins -d '{"off":[],"on":["saved_agents"]}'

on lists the opt-in groups that are on and replaces the earlier list; omit it to keep them. An opt-in group in off is ignored. The group in GET /api/chats/{id}/tools has opt_in: true, and usable and reason say whether it can serve the chat now.

Past chats

The group Past chats (history) lets the model recall what you said in earlier chats. It is off until you switch it on in the chat’s Tools menu, like Saved agents. It has two read-only tools:

• search_chats (query, scope, limit, since) finds messages in your earlier chats with the same search as the web UI. scope is this_chat (this conversation, including parts that compaction took out of the model’s context), this_agent (chats with the same saved agent) or all. It returns at most 10 hits; each has chat_id, title, date, message number (seq), who wrote it and a snippet of at most 300 characters.
• read_chat (chat_id, from_seq, limit) reads the user and assistant messages of one chat that a search found, from a message number. It returns at most 20 messages and about 6 KiB, and says which message number to ask for next when more follow.

The model is told to use them only to recall what you said, to say plainly when it finds nothing, and never to quote other people’s messages back. Every result is wrapped as untrusted text, because an old message can contain anything: a line in it never changes a switch, a grant or a file.

What the tools never reach:

• Another user’s chats. The search applies your account in the query itself.
• Private chats (a chat with the notes of memory switched off), the runs of sub-agents, and every chat that no person started: triggers, jobs, pages and messaging apps. A messaging chat holds the words of other senders, so no chat of a messaging app is returned.
• Deleted chats: a chat leaves the search index in the same step that deletes it, and text that regenerate or edit removed leaves it too.

Who has the tools:

• A chat of yours, when you switch Past chats on.
• A saved agent, only when you grant it Read your earlier chats (history.read), which is off by default. Saving the agent with the grant turns the group on for its chats. An agent that works in a folder may search only its own chats (this_agent), never all, and read_chat refuses chats of other agents.
• Never a run that starts by itself (trigger, job), a chat that a messaging app started, or a sub-agent, whatever its parent has.

Each call writes one log line with the tool, the user, the chat, the scope, a hash of the query, the number of hits and the chat IDs returned. It never holds a query or a message.

Running commands

A chat runs commands and code with one tool, bash. Who serves it depends on the server:

• The Sandbox. With the Sandbox add-on installed, running and on for the chat, bash runs in an isolated sandbox. The add-on’s bash replaces the built-in one (see Tools that replace a built-in tool), so the chat never has two.
• This machine. Otherwise, when an administrator allows it, the built-in bash runs commands directly on the machine that runs LocalAI, with no isolation. This covers a server with no Sandbox, a chat that switched the Sandbox off, and a Sandbox that is stopped or cannot run.
• Nothing. With neither, nothing in the chat runs code.

A chat whose agent works in one folder runs commands only in the Sandbox, never on this machine. Its sandbox has the agent’s folder at /workspace/home and the chat’s own folder at /workspace/chat.

At every turn the model is told in one short block which of the three holds. With host commands the block says that bash runs on this machine with no isolation and with its network, and tells the model to be careful: no destructive or data-sending commands outside the task unless you asked. When nothing runs, the block says that the model must not say or imply that it ran something, nor send a sub-agent to run it; it writes the result as a file (text, CSV, Markdown, HTML, JSON) or gives you the script, and tells you how to get commands.

A skill can say that it needs commands with requires: [exec] in its frontmatter (see Skills). In a chat that cannot run commands, such a skill is listed to the model as “unavailable here: needs command execution”, without the path to its procedure, so the model explains instead of starting.

Background jobs

A command that runs for minutes or never ends (a build, tests, a dev server, a download) does not fit in one bash call, which stops after at most 30 minutes. The model starts it with the job tool and keeps working. job is one tool with an action:

job is offered exactly when the chat has bash, from the same provider, and the same switch (the shell group of the chat’s tools) turns both off. A chat whose bash the Sandbox serves never runs a job on this machine. In mode ask for commands on this machine, start shows the same card as bash, with the whole command, and the approval of the start covers the input of that job: no card per input. The card says so under the command, and so does the answer of start. Input is still refused when the chat could not run a command now, and every start, input and kill of a job on this machine is written to the audit of the commands. When the tools of the chat cannot be read, or the add-on that serves its bash cannot work, start says so and runs nothing. A run that nobody watches (a trigger or an agent job) needs, for start and input, what its bash needs: on this machine act.files and act.spend, in the Sandbox the act grant of the add-on.

A job has the fixed environment of the built-in bash, its own process group, and one ring of the last 256 KiB of its output (standard output and error together). Output that the ring dropped is reported as lost bytes. The output the model reads is data, not an instruction.

A job on this machine owns its process group: when the main process of the job returns, what it left running in the background is killed too, so job start "./server &" ends at once. Start a server as the main process of the job (./server). The same holds when the job is stopped, at its lifetime and when the server stops. If the server stops without cleaning up, the next start of the built-in bash kills the groups that the earlier run recorded. Once close_input closed the input of a job, a later input says that the input is closed.

Limits. 4 running jobs per chat, 8 per user, 32 per server, each for at most 2 hours. The server counts the jobs that run on it and the Sandbox add-on counts its own, so the jobs on this machine and the jobs in the Sandbox have separate limits. The jobs of sub-agents count for the user. A start holds its place before it runs, so two starts at once never pass a limit together. The per-user limit of the jobs on this machine is counted on each server. A finished job stays readable for 30 minutes (at most 16 per chat; the server keeps at most 128 finished jobs of its own). A job ends when it exits, when the model or you stop it, at its lifetime, when the chat is deleted, when the shell tools are switched off for the chat (within 30 seconds), when the chat’s agent gets a folder that confines it, and when the server stops. A job on this machine also ends when the administrator switches commands on this machine off (within 30 seconds); that setting does not govern the Sandbox, so it does not end Sandbox jobs. A job holds the scratch folder of its chat (on this machine or in the Sandbox): the server does not evict it, put it to sleep or refresh it while the job runs, so a command run in the same chat meanwhile does not see files that changed elsewhere until the jobs end. A user has at most 4 such folders with work in them, so jobs run in at most 4 chats of one user at once; a start in a fifth chat says so.

Files. What a job writes reaches your files at the next checkpoint of the chat: each bash call, and one more when the job ends (a change named Job job-4k2x7q: build). A bash call that runs while the job writes a file may save it half written; the next checkpoint corrects it.

In the Sandbox. When the Sandbox serves the chat’s bash, the job runs in the chat’s sandbox, inside the add-on. The sandbox stays awake while a job runs. It needs a Sandbox add-on of feature level 6; with an older one, job start says so and runs nothing elsewhere (see Execution provider and status payload). A call that must make the sandbox again (a new profile, folder or mode) ends the chat’s jobs first and says so at the top of its output.

The add-on does not tell the server when a job ends; the server asks it. Your list of jobs, the model’s job list, a wait on the job and a start in the chat each ask once per chat, and the server that started a job (or saw it running) asks every 30 seconds while the chat has a running job. That sweep also ends the chat’s jobs when the shell tools are switched off for it, when its agent gets a folder that confines it (seen on two sweeps in a row), when the chat is gone, or when the sub-agent that started them has ended; the end reason says which. The sweep is per server: after a restart of that server, it follows a chat again from the first time it shows the chat’s jobs, and until then the 2-hour lifetime bounds them. Starts, input, kills (with their reason) and the ends the server sees are written to the audit of the Sandbox jobs; a start the add-on refused ran nothing and is not written.

A Sandbox job reaches the network through the same proxy as bash. The proxy cannot tell which process opened a connection: while a bash call of the chat runs, a connection of a job counts as that call’s, so a network card that a job causes then looks as if the command of the call asked. When no call runs, a connection counts as the oldest running job’s, and a host that would need your yes is blocked with the reason unattended, even while the model is still writing its answer; curl or pip print the block into the job’s output. The add-on keeps at most 64 jobs it can save files and reach the network for; a start beyond that says so and runs nothing.

Sub-agents. A sub-agent gets job exactly when it gets bash, with the same limits and the same checks. It never sees a card, so on this machine it runs a job only in mode on. Its jobs end with it; the parent can list, read and kill them, not write to them. See Jobs and stall waits of sub-agents.

See and stop a job. The jobs of a chat are listed above the message box, with the loops and waits: the label the model gave, the state in words (running, no output for a while, exited with its status, stopped, killed, lost), where it runs and for how long. Finished jobs fold into one line. The list never shows the command. Stop ends a running job as you: term, then kill after 10 seconds, and the end reason reads “stopped”. The same is POST /api/chats/{id}/jobs/{job}/kill, for the owner of the chat only. The jobs are also in the jobs field of GET /api/chats/{id} and of GET /api/chats/{id}/loops: id, label, state, end, exit, started, ended, last_output, bytes, provider and whether a sub-agent started it.

Distributed mode. A job is a process in the memory of one node (or of the Sandbox add-on), so jobs are per-instance by design: they are not shared and not moved. A restart of that process or the loss of that node ends the job, and its output and exit status are gone. The chat record keeps an index of its jobs (id, node, provider, state, never the command), so a turn that runs on another node still reads, writes to and kills the job, by a request to the node that runs it. A node that answers but does not know the job (it restarted) marks the job lost at once. A node that nobody answers for marks it lost only after three asks over at least 30 seconds, so a short break does not lose a running job; until then the model is told to try again and a wait counts a failed check. A read or a stop of a lost job still asks the node, and a job it still knows is live again. A wait on a lost job wakes with a text that says the job is gone with its node and that the condition is not known. If the node only answers slowly, nothing changes and the model is told to try again.

Network of the Sandbox commands

The Sandbox has no network device: its commands reach HTTP and HTTPS only through a proxy that asks LocalAI about each connection (see Network access). Each chat has a Network row in its Tools menu with three choices:

• Off: commands reach nothing.
• Package registries: commands reach the package registries only (PyPI, npm, Go modules, crates.io, RubyGems, Maven Central and GitHub releases), so pip install, npm install, go get and cargo build work.
• All public sites: commands reach every public host.

The highlighted choice is what applies: the lower of the choice of the chat and the limit. When a chat asks for more than the limit (for example All public sites with the limit Off), the row shows the limit highlighted and says in a line what the chat asked for. Where commands run on the server’s own machine, the row is a line saying they use its network; network limits need the Sandbox add-on.

A choice above the limit an administrator set (chats_egress_ceiling) is greyed out with Limited by your administrator. When the limit is off (the default), the row says Off: the administrator has not allowed network access and gives an administrator a link to the Settings tab of the add-on that runs the commands, named by its title; anyone else is told to ask one. The model is told the same, so it reports that the server’s setting blocks the network instead of waiting for an approval. A new chat starts with the administrator’s default. A fork keeps the choice and the allow rules of the chat it copies. The choice and the rules live with the chat on the server, never in your files, so the code that runs in the Sandbox cannot change them. Rules and requests under the row lists the hosts this chat allowed or denied, with a button to remove each, and the requests that asked. When an administrator keeps a list of always-allowed hosts (chats_egress_allowed_hosts), the row says how many there are and the panel lists them, read only, under Always allowed by your administrator. They are reachable whenever the network of the chat is on (Package registries or All public sites), without a card; with the network off they wait until you turn it on.

The model knows that curl, pip, npm and git work in the Sandbox within this setting. It prefers web_fetch and web_search to read or search web pages when the chat has them, and uses curl for APIs, downloads and installs.

When a command asks for a host the chat does not allow but the limit would, the chat shows a card: A command in this chat wants to reach host:port, with Allow once (for the rest of that command), Allow for this chat and Deny. The command waits up to 60 seconds for your answer and goes on by itself after it. The card stays with the chat, so a reload shows it; once answered it becomes one line under the bash call that asked, such as Allowed for this chat by you, 14:02. A host inside your network needs an administrator to allow it. If the limit was lowered while the card waited, the card has no buttons: it explains that network access is off (or limited) on this server and who can change it, and it ends as Refused: the server’s network limit does not allow it. A trigger, a connector run or a sub-agent never shows a card.

When commands run on this machine instead, the row is one line, Commands run on this machine and use its network: these settings do not apply there.

The Network row is drawn by LocalAI for the add-on that runs the chat’s commands, when that add-on has the network-policy host control (the Sandbox has it). With an add-on that runs commands but does not have it, the Tools menu has no Network row; the limit and the default still apply to its commands.

The routes, for the chat’s owner (another user’s chat is 404):

The chat’s event stream carries egress_consent (ids: [card id], text: host:port) when a card asks and egress_card when the chat’s network changes, so every open tab reads it again. Administrators read the settings in force and the audit with GET /api/chats/admin/egress and GET /api/chats/admin/egress/events?limit=&user=&chat=&verdict=&host=, and see both on the Settings tab of the add-on that runs the commands. Its sandbox field names the add-on that runs the commands now: of the running add-ons that replace bash, the one chosen in chats_tool_providers or the one installed first, and none when the chosen one is stopped. It is read from the add-on host each time, so it is right after a restart and the same on every frontend of a cluster.

Sandbox profile

A Sandbox add-on that declares profiles (the Sandbox does: base and media, see Sandbox profiles) gives the Tools menu a Profile row next to the Network row. It shows the profile the next command runs and lets you pick another one. A new chat gets the default of the administrator (media when the administrator sets none), or the profile of its saved agent. Switching restarts the sandbox at the next command: your files stay, running processes and installed packages are lost, and the row says so before you switch. While the image of a profile is pulled for the first time, the row shows the progress. If the profile cannot be used, commands run in base and the row says so. A running chat keeps its sandbox until it restarts, and the row shows when a newer image is available. A profile the administrator did not give you is shown but cannot be picked.

The model has one tool for this in the Run commands group, sandbox_profile: the action list gives the profiles, their programs and whether you may use each one, and the action use switches. It follows the rules of the row. A saved agent has a sandbox_profile field, for its unattended runs and as the starting profile of its chats.

Commands on this machine

The built-in bash is for a server that cannot run the Sandbox. Read this before you allow it:

First start. While no model is installed, the Home page of an administrator lists the first steps. The optional last step, Run code safely, offers to install the Sandbox add-on (it opens the add-on browser at the Sandbox) and says what happens without it: the model can only use the built-in host bash fallback, which has full network access and no isolation. Press Skip to hide the step (the browser remembers it). The step is not shown when the Sandbox is already installed, or when add-ons are off.

• No isolation, full network. A command runs as the user LocalAI runs as. It can read every file that LocalAI can read and reach the internet, your local network, the LocalAI API on the loopback and cloud metadata addresses. Nothing blocks the network without privileges, so there is no “no network” option, and the network settings of the Sandbox (chats_egress_*) do not apply. Install the Sandbox to isolate commands.
• Never as root. When LocalAI runs as root, the built-in bash is not offered.
• Never for an agent limited to one folder. A chat whose agent works in one folder (and its sub-agents) never gets the built-in bash, whatever chats_host_exec says: a command here can read every file LocalAI can read, so nothing keeps it in that folder. Such a chat runs commands only in the Sandbox, and its Tools menu says why. See Folders of an agent.
• Your files. Each chat gets a scratch folder with your files: home/ there is /workspace/home of the file tools, and shared-<name>/ is a shared folder. A command starts in the chat’s work folder, $WORK, which is home/Chats/<chat>/work (home/ itself when the chat has none). So your home is $WORK/../../.. and a shared folder is $WORK/../../../../shared-<name>; quote every path. The skills are there too, read-only, at the names the file tools use: shared-skills/ (shared by an administrator), shared-builtin-skills/ (built in) and shared-addon-skills/ (from add-ons), so user-written skill scripts can run in place. Sandbox document procedures require the Sandbox guest instead; host commands do not provide its dependencies. A shared folder named skills is at shared-skills 2/. After each call, what the command changed is saved to your files as one change of the chat, which you can undo in Files, History; a file you or the file tools changed meanwhile is read again before the next call.
• A clean environment. A command gets PATH, HOME, LANG and TZ only: no API key, database address or token of the server.
• Limits. A call stops after timeoutSeconds (120 by default, 1800 at most), and the whole process group is killed then, when the turn is stopped and when the output passes 64 KiB. One call runs at a time in a chat, and at most four chats of one user run commands at once.
• Audit. Every call is recorded: user, chat, command (cut at 4 KiB), exit code, duration and whether it timed out. A line has a kind: run for a bash command, and job_start, job_input (the text written, cut at 4 KiB), job_kill and job_end (exit and duration) for a background job, with its job id. The record is kept in the auth database (in a cluster, shared by every frontend), in a file under the data path, or in memory. The server log has one line per command with the prefix [host-exec]. Administrators read the audit with GET /api/chats/admin/host-exec/events or the assistant tool list_host_exec_events. Lines older than chats_egress_audit_days (default 30, the retention of the command network audit) are removed daily; in a cluster one frontend does it, under an advisory lock. The file store also keeps at most 10000 lines.

The runtime setting chats_host_exec (Settings, Tools, the bash row; LOCALAI_CHATS_HOST_EXEC) decides who gets it:

Empty is the default: off on a server with accounts, ask without. In ask mode the chat shows a card under the running call: “Run this command on this machine?”, the command, and Run once, Always on this instance (saves chats_host_exec: on) and Don’t run. A person who is not an administrator can only refuse it. The card lives as long as the call waits, at most 5 minutes. The server keeps it with the chat, so a reload, or another browser or frontend, shows it again and it can still be answered; once the call ends the card is gone and the call’s line says how it ended. GET /api/chats/{id} carries the waiting card as host_consent (id, command, and job, true when the command starts a background job) while the turn that asked runs. The card names that turn: a card of an earlier turn is not shown, also while a later turn runs, and is cleared when the next turn starts. An answer to a card with nobody waiting on it (its turn has ended, its frontend stopped, or a newer card replaced it) is 410 consent_expired, and the chat shows the card as not answered: the command did not run. The answer is sent with:

curl -X POST .../api/chats/3f1c.../host-exec/consent -d '{"id":"<id of the host_exec_consent event>","decision":"once"}'

Only an administrator may send once; anyone who owns the chat may send deny. An answer without the card id, or with any other decision, is 400 for everyone, also for an administrator. The first answer counts: the same answer again is 204, the other one 409 already_answered. The call’s line in the chat then says what happened: run on this machine, allowed once, refused or not answered (card host_exec). A call that the Sandbox served carries the card tool_provider with the add-on’s ID.

Distributed mode. The scratch folders belong to the frontend that runs the turn, like the Sandbox’s sandboxes: your files are the record, and a chat whose next turn runs on another frontend gets a new folder there. The waiting card is stored in the chat record (state mode: shared), so any frontend can show it; its answer is written to the card in the record first and then sent on the chat bus to the frontend that runs the turn, which also reads the card again every two seconds, so an answer given through any frontend reaches it within two seconds even when the bus message is lost, as for the network cards. A card left by a frontend that died is not shown and cannot be answered: its turn no longer holds the chat, and the reaper, or the next turn, clears it. The network cards of the Sandbox follow the same rule. The setting is a runtime setting like the others.

What the web interface is told

GET /api/chats/{id}/addons says the same for the web interface in commands: available, off (the selected provider is off for this chat, or its agent does not name it, and the built-in bash is not allowed), unavailable (installed, but it cannot run commands on this server; commands_reason says why) or none (no add-on that runs commands is installed for you). When commands run, commands_provider says who serves bash (builtin, or the add-on’s ID) and commands_isolation says isolated or host. commands_consent is ask when each command waits for the card, and commands_fallback with commands_fallback_reason name the add-on that would serve but does not (off, or its reason). The Tools menu uses this selected-provider response, not private add-on status data. It labels commands as isolated only when the current provider explicitly reports available, isolated execution. Missing, loading and unknown observations remain unknown. Host execution shows a warning without recommending a specific add-on. The first-run guide and native tool settings do not recommend an add-on by ID.

curl -s localhost:8080/api/chats/$ID/addons
# {"addons":[],"commands":"available","commands_isolation":"host","commands_provider":"builtin","commands_consent":"ask"}

The connections of an add-on

Some add-ons run their tools with a token that you keep in a connection (for example the GitHub add-on or the Jellyfin add-on). Any add-on that declares a credential in its manifest works this way. LocalAI never chooses the connections for you, and a chat can use more than one for the same add-on:

• With one connection for the add-on, it is enabled and cannot be switched off separately.
• With several, the add-on’s row in the Tools menu has a Connections list with a checkbox for each. You tick the ones this chat may use. Until you tick one, the tools of the add-on are not offered to the model, the row is off and says “Choose at least one connection to use these tools”. Ticking a connection switches the add-on on.
• With none, the row says “No connection yet” and links to the Connectors page.
• A saved agent can name a set of connections for the add-on. A chat of that agent uses that set, shows it read only, and cannot change it. An agent with no set follows the same rules as a chat.
• A chat that a connector binding started uses that binding and no other.

The set is stored with the chat, like the other switches, and survives a reload, a fork and the runs of the triggers that the chat proposed.

How the model picks one. The tools keep their names. With exactly one connection enabled, nothing changes for the model: the tools run with that connection. With two or more enabled, LocalAI adds one argument, connection, to every tool of the add-on, reads and writes alike. It is required, and its value is one of the enabled connections by name. The name is the connection’s name in lower case, with each run of other characters turned into a hyphen (“Work account” is work-account); the description of the argument lists each name with the name you gave the connection. The add-on never sees the argument. LocalAI checks the name against the connections enabled for this chat, not against all your connections, so the model cannot use a connection you did not enable, whatever a tool result or a file says. A missing or unknown name returns a plain sentence that lists the allowed names, and nothing is sent. A tool that changes something never runs without the name, also when changes are made without asking.

The names of your connections to one add-on must differ (case and punctuation do not make a new name): saving a connection with a name that another has is a 400. Connections saved before this rule keep working, and LocalAI gives a repeated name a numeric suffix in the list the model sees.

The repository (or other resource) list of the connection that was named is the only one that applies: a call that names a repository that is not on that connection’s list is refused with the list of that connection. The tool result and the confirmation say which connection acted (“as Work, repository acme/widgets”). When a change waits for you to confirm it, the card shows the connection first, and the change is applied with the connection it was previewed with, even if you change the set meanwhile. The audit line of each use of a token carries the binding ID.

In GET /api/chats/{id}/addons such an add-on has credentialed: true, connections ([{id, name, handle}], oldest first; handle is the name the model uses), enabled_connections (the IDs this chat may use), connection_by (chat, agent, binding or only) and needs_connection. PUT /api/chats/{id}/connections {"addon": "<add-on id>", "connections": ["<binding id>", ...]} sets the set (an empty list clears the choice; 400 when the agent of the chat names a set or a binding is not yours for that add-on; the older single connection field is read as a set of one). The draft list takes connections=<add-on id>:<binding id>, once for each binding, and POST /api/chats takes switches.connections ({"<add-on id>": ["<binding id>"]}). Stored data and requests that hold a single binding ID for an add-on are read as a set of one. A call that comes from no chat, such as the add-on’s own page, can use a connection only when you have exactly one; otherwise it is refused with select_connection.

Long conversations

When a chat fills the model’s context window, the older part is compacted so the model can go on. The transcript keeps every message; only what the model sees shrinks. A compacted event reports the size before and after. The window comes from context_size in the model’s configuration.

Reasoning of earlier turns

A chat asks the model’s chat template to keep the reasoning of earlier turns (chat_template_kwargs.preserve_thinking). Some templates, such as the Qwen 3 family, otherwise keep the reasoning of the last turn only. A new turn then renders the earlier answers without their reasoning, the prompt changes from the first answer of the turn before, and a backend with a prompt cache (llama.cpp) must read everything after that point again before the reply starts. A template that does not know the argument ignores it. To turn it off for a model, set chat_template_kwargs: {preserve_thinking: false} in its configuration. A model served by a remote proxy is not asked.

The context window a chat needs

Before you type, a chat already sends a fixed block to the model: the system message, the always-on tools, the LocalAI tools (or the three tool-search tools when they are deferred) and the chat template. That block is about 7,000 tokens for a regular user and more for an administrator, and the chat loop needs at least 1,024 tokens free for the reply. A model with a smaller window fails every turn with the failure code context_too_small, and so would every new chat. A window that is only just large enough makes the chat compact its conversation on every turn.

You do not have to do anything for a model that sets no context_size. When the model can serve chats, LocalAI aims at 32768 tokens, capped by the window the model was trained for, and steps down through 24576 and 16384 (and only then 8192, 6144 and 4096) when the next window does not fit the memory of the machine. Embedding, rerank and other models that cannot serve a chat keep the smaller automatic window of 8192.

A context_size that you set is never changed, even when it is below the minimum: it stays as you wrote it. The chat tells you instead. When the window of the chat’s model is below the minimum, a banner appears above the message box, and GET /api/chats/{id} returns a harness object with ok, window, minimum, recommended, can_fix, admin and source.

• An administrator sees whether the recommended window fits the memory of the machine and a button that sets the model’s context_size to it, or to the largest step that fits and reaches the minimum. When nothing fits, the banner suggests a smaller model.
• A regular user cannot change a model. The banner lists the installed models whose window is large enough, to move the chat with one click, or says to ask an administrator.
• source is model when the model’s window is too small, and chat when the chat’s own context_size setting is below the minimum. The owner of the chat can change that setting.

Changing the context_size of a model needs an administrator; the server refuses it for anyone else, whatever the page shows. A turn that fails because the window is too small ends with the failure code context_too_small and a message that names the window and the minimum.

Compact or clear the context yourself

You do not have to wait for the window to fill. Two calls change what the model sees from the next turn on; both answer 409 while a turn runs, and the transcript keeps every message either way.

# Summarize the older part now, as the chat does when the window fills. It
# takes a while: the model writes the summary.
curl -X POST .../api/chats/3f1c.../compact
# {"before":18250,"after":4120}

# Start fresh in the same chat. Its files, title and switches stay.
curl -X POST .../api/chats/3f1c.../clear
# {"cleared":true}

• Compact keeps the last messages as they are and puts a summary in place of the ones before. It answers 400 when the conversation is too short to compact. The transcript gets a line with role compacted and the sizes in before and after (tokens, the same estimate as the compacted event).
• Clear writes a line with role cleared. From then on the model sees nothing above it. It answers 400 when the model sees no message to clear. A cleared event tells the other open pages to read the transcript again.
• A fork from a line above a cleared line keeps what the model saw there. A regenerate or an edit rebuilds what the model sees from the transcript after the last cleared line. The JSON export and the Markdown export show both lines, and an import keeps them.
• Both calls hold the chat the way a turn does, so in a cluster no frontend starts a turn on the chat while they run. Messages sent meanwhile wait and go when the call ends. Nothing is kept outside the chat store.

Messages sent with a skill or a saved agent

A message can carry skill, a skill of the chat, or agent, the id or the name of one of your saved agents. With a skill, the model gets the text of the skill’s SKILL.md before your message, for this turn only; the transcript keeps your words, and the line has "invoked":{"kind":"skill","name":"review"}. With an agent, the model is asked to start that saved agent as a sub-agent with the task (the chat must have Saved agents switched on). A regenerate runs the skill again.

curl -X POST .../api/chats/3f1c.../messages -d '{"text":"check the diff","skill":"review"}'
curl -X POST .../api/chats/3f1c.../messages -d '{"text":"check the draft","agent":"rev1"}'
# An unknown skill: 400 with the names of the skills of the chat. An unknown
# agent, another user's, or saved agents off for this chat: 400.

Such a message starts a turn. While a turn runs it does not wait like other messages: it answers 409, and you send it again when the model has answered.

Slash commands

Type / in the message box of a chat, or on Home, for the list of commands. Typing filters it; arrows move, Enter runs the command, Tab completes it, and Esc closes the list. A command that takes an argument lists the choices as you type it: /agent lists your saved agents, /skill the skills of the chat and /model the chat models, /loop stop the loops of the chat.

Home offers the same commands, less /compact, /clear, /goal, /loop and /about: a chat that does not exist yet has no context. /<skill> and /agent work there because the chat is created with the switches you chose first.

Run a skill

Every skill the chat can use is a command of its own: /review check the diff sends “check the diff” with the review skill. The list marks where each skill comes from (built-in, add-on, shared or yours). A skill whose name is a command, such as a skill named new, is reached with /skill new. A skill that is switched off, replaced or for another user is not offered.

The message goes with the name of the skill. The model gets the text of the skill’s SKILL.md before your message, for this turn only; the transcript keeps your words and shows the skill as a chip. A regenerate runs the skill again.

Hand a task to a saved agent

/agent Reviewer check the draft asks the model to start the saved agent Reviewer as a sub-agent with the task (see Saved agents as sub-agents). The chat must have Saved agents switched on in its Tools menu; while it is off, the list offers to switch it on.

A command message starts a turn: while a turn runs, send it again when the model has answered. The API of these messages is in Messages sent with a skill or a saved agent.

MCP tools

A model that has MCP servers and sets mcp.auto: true offers all of them to its chats, as it does for /v1/chat/completions. A user needs the mcp feature, and LOCALAI_DISABLE_MCP turns MCP off for the whole instance. A tool cannot take the name of a built-in tool such as spawn_agent.

You can also add MCP servers of your own, stored on the server: see MCP servers. Your enabled connectors are offered to your chats next to the model’s servers; the model’s own configuration is not changed.

Prompts and resources as context

MCP servers can offer prompts (ready-made instructions with arguments) and resources (documents the server holds). A chat can list them for the servers it can use now, which means the servers of the model, less the ones you switched off for the chat, or the ones the chat’s saved agent grants, and your enabled connectors. You can add any of them to a message as context for that turn:

curl .../api/chats/3f1c.../mcp/prompts      # {"prompts":[{"server":"connector:ab12","name":"review","arguments":[...]}]}
curl .../api/chats/3f1c.../mcp/resources    # {"resources":[{"server":"wiki","uri":"wiki://home"}]}
# Preview one:
curl -X POST .../api/chats/3f1c.../mcp/prompts -d '{"server":"connector:ab12","name":"review","arguments":{"lang":"Go"}}'
curl -X POST .../api/chats/3f1c.../mcp/resources/read -d '{"server":"wiki","uri":"wiki://home"}'
# Send them with a message. The server expands them as you and puts the text before yours.
curl -X POST .../api/chats/3f1c.../messages -d '{"text":"Go ahead","context":[
  {"server":"connector:ab12","name":"review","arguments":{"lang":"Go"}},
  {"server":"wiki","uri":"wiki://home"}]}'

A server the chat cannot use is 403 mcp_refused, and the message is not sent. A server that does not answer is 502 mcp_error. Binary parts of a resource are left out, and the text is cut at 256 KiB. The expanded text is part of the message in the transcript.

Switch tools off for one chat

The Tools menu over the message box lists the groups of built-in tools, the add-ons you may use, the MCP servers of the chat’s model and your connectors, with a switch each. What cannot be used now is shown off, with the reason (a connector that is switched off, a model server that the model does not use by itself). A switch takes effect at the next turn. Switches only take away: a chat with a saved agent lists only what the agent grants and never gets more than that. A trigger run with no agent copies the switches of the chat that proposed it.

The menu groups the rows under Built-in tools, Add-ons, MCP servers of the model and Your connectors. Each row has the name, a line of text when there is something to say (why it cannot be used, how the Sandbox runs commands), a chip with the add-on that serves a built-in tool (“Served by add-on searx”), the number of tools of an add-on, and the switch. A click on the name also toggles the switch, and Space toggles a focused switch. The header gives the count of what is on among what can be used (“4 of 7 on”), with Select all and Disable all. A group with two or more switches has All on and All off for that group only. These buttons never change a row that cannot be used, and Select all leaves Saved agents off: you switch it on by hand. They send one request for each kind of switch (built-in tools, add-ons, MCP servers and connectors). A change that the server refuses goes back, and a line at the bottom of the menu says so. On a phone the menu opens as a sheet at the bottom of the screen.

curl -s localhost:8080/api/chats/$ID/tools
# {"addons":[...],"servers":[{"name":"crm","off":false,"usable":true}],
#  "connectors":[{"id":"c1","name":"Docs","off":false,"usable":true}],"off":[]}
curl -s -X PUT localhost:8080/api/chats/$ID/mcp -d '{"off":["crm","connector:c1"]}'

off holds the name of a server of the model, or connector:<id>. At most 200 switches.

The built-in tools switch by group. Every group is on until the chat switches it off, so a chat that never touches the menu works as before:

curl -s -X PUT localhost:8080/api/chats/$ID/builtins -d '{"off":["web","files"]}'

The two LocalAI groups are large, so on a small context window a chat may not send them in full: it sends tool_search, tool_describe and tool_call instead, and the model finds and runs their tools through them, under the same permissions. The setting chats_tool_search (auto, on or off) decides; with on, the tools of the user’s MCP connectors load on demand in the same way. See Tool search. The tools panel marks such a group with "deferred":true.

off replaces the earlier list, and a name that is not a group is refused (400). A group the server does not offer is not listed: Your files and Images and audio need the files, Images and audio the helper models, Knowledge the collections. A group that this chat cannot use now is listed as not usable with the reason, for example Knowledge for a user without the collections feature.

Run commands governs bash from both providers: switched off, the chat has no bash, and the add-on list says "commands":"switched_off". The row names who runs the commands (Sandbox with “Commands run isolated”, or This machine with a warning), and the notice about commands on this machine stays at the top of the menu. When nothing can run commands, the row is not usable and gives the reason of that notice. The Sandbox row under Add-ons stays for the add-on’s other tools.

What the model is told follows the tools it has. With Your files off it hears nothing about the file tools: no hint to save files with write_file, no work folder, no pointer to AGENTS.md, and no line about writing skills when nothing can save a file. The list of the chat’s files stays, with a line that the model cannot open them. The files pane, uploads and previews work as before, and load_skill stays: it follows the Skills menu. With Images and audio off the model is not told to call describe_image. With Run commands off the model is told that you switched commands off and where to switch them back on.

A sub-agent follows the switches of its parent chat: it never gets a tool of a group the parent switched off. A trigger run with no agent copies these switches from the chat that proposed it, as it copies the others. Each group keeps its own rules for the runs that start by themselves (for example a trigger or connector run never gets the trigger tools). load_skill, page_errors (it reads the errors of a page’s script, see Pages), open_page (it opens a page of your home in the dock beside the chat) and the goal and loop tools have no switch.

The trigger tools have a group too, triggers: propose_trigger, list_triggers, update_trigger and delete_trigger switch together, and the menu shows them as one Triggers row. It is on by default; {"off":["triggers"]} takes the four tools away from that chat. A chat started by a trigger or a connector and a sub-agent never have them, and the row then shows as not usable with the reason. The row also shows as not usable when you do not have the triggers feature, and it is not listed at all when the server runs no triggers (LOCALAI_DISABLE_TRIGGERS). The group has no runtime setting: the start-up switch governs it. See Proposals.

The saved agents group (saved_agents) is opt-in: it is off until on names it. See Saved agents as sub-agents.

Interactive tool pages (MCP Apps)

A tool of an MCP server can declare an interactive HTML page in _meta.ui.resourceUri, as the MCP Apps extension defines. When the model calls such a tool, the chat shows the page under the tool line, with the arguments and the result of the call. This works for your connectors and for the MCP servers of the chat’s model. The page appears as soon as the tool call ends, while the turn goes on, and it stays when the turn ends or the chat is opened again.

A live tool_end event carries the reference of the app (server, tool, resource, visibility) and seq, the number of the call’s line in the transcript. The arguments and the full result are not in the event. A client that wants them reads that one line with GET /api/chats/{id}/messages?after=<seq-1>&limit=1, which has the same checks and size limits as the whole transcript. Because the line is in the shared store, this works whichever frontend runs the turn. A client that misses the event or cannot read the line shows the text result, and finds the app in the transcript when the turn ends.

The MCP connection stays on the server, so two routes of the chat carry the page and its calls. Both answer only for a server that the chat may use at that moment: not switched off in the chat’s tools panel, named by the chat’s agent if it has one, and, for a connector, yours and enabled. You need the chats and mcp features. Anything else is 403 with the type mcp_app_refused.

# The page of the app. server is connector:<id> or the name of a server of the model.
curl -s "localhost:8080/api/chats/$ID/mcp-apps/resource?server=connector:c1&uri=ui://clock/app.html"
# {"uri":"ui://clock/app.html","mime_type":"text/html;profile=mcp-app","html":"...","meta":{"csp":{...},"permissions":{},"prefersBorder":true}}

# A tool call from the page.
curl -s -X POST localhost:8080/api/chats/$ID/mcp-apps/call \
  -d '{"server":"connector:c1","tool":"refresh","arguments":{"zone":"UTC"}}'
# {"result":{"content":[{"type":"text","text":"..."}],"structuredContent":{...}}}

Rules the server applies:

• The resource must be a ui:// URI that a tool of the same server declares. No other resource is read. It must be text/html (with the mcp-app profile or none) and at most 4 MiB.
• A tool call must name a tool of the same server whose _meta.ui.visibility includes "app" (the default is ["model","app"]). A tool in the add-on namespace or with the name of a built-in tool is refused. The call has the same time limit as a call of the model, its arguments are at most 16 KiB, and its result is cut at 256 KiB.
• A tool with visibility: ["app"] is not offered to the model.
• The answers never hold a token or a header of a connector, and an error from the server is cleaned of them.
• In distributed mode, apps work for connectors. The MCP servers of the model run on workers there, so their apps answer 409 with the type mcp_app_unsupported.

The tool_end event and the transcript line of a call with a page carry app: server, tool, resource_uri and visibility. The transcript line also has input and result (the full MCP result, at most 256 KiB), which the page needs. The text of the line keeps its usual 2 KiB cut, and the model sees only the text of the result. The event has no input or result: read the transcript for them.

The web interface shows the page in an iframe with sandbox="allow-scripts" and nothing else. The page has no access to the interface (no same-origin access, no cookies, no storage), cannot navigate the top window and cannot open windows. Its content security policy allows no network by default. A page can ask for https and wss origins with _meta.ui.csp (connectDomains, resourceDomains, frameDomains and baseUriDomains); the server and the interface drop anything else. Browser permissions such as the camera are not granted. The interface reads messages only from that frame and ignores the rest. It supports ui/initialize, tools/call, ui/notifications/size-changed (height between 60 and 600 pixels), ui/message, ui/open-link and ui/request-display-mode; any other request gets the JSON-RPC error “method not found”. A message that the page sends with ui/message is shown as a suggestion that you send or dismiss, never sent by itself. A link from ui/open-link must be http or https and opens only when you click it. When the page cannot be loaded, the chat shows the result as text.

Skills

In the web UI, the Skills item in the sidebar, right after Knowledge, opens the page where you write, change and delete skills. Every chat can use them, and agents use the ones you add to them. You can also open the page from the Manage skills link at the bottom of the Skills menu in the composer, or by typing /skills in the message box.

A skill is a folder with a SKILL.md: a name, a one-line description and a procedure the model reads when a task matches. An optional requires key lists what the procedure needs; today the only value is exec, a way to run commands (requires: [exec]). A chat that cannot run commands lists such a skill as unavailable (see Running commands). At each turn the chat’s prompt lists the skills it has, by name and description only, and tells the model to call the load_skill tool with a skill’s name before a task that matches it. load_skill returns the instructions of the skill, the text after its frontmatter. It offers exactly the skills of that list: for each name the nearest skill, not switched off, and the skills of the add-ons the chat can use now. Any other name is refused with the names of the chat’s skills and the near ones first (for example Did you mean pdf? for PDF).

An optional sandbox key names the sandbox profile the skill works best in, for example sandbox: media for a skill that cuts video with ffmpeg. It is a hint and nothing more. The index marks the skill as preferring that profile. When the chat runs another profile, load_skill adds a line that tells the model the skill wants the named profile, and the model may offer to switch with sandbox_profile (action use). It never switches by itself and nothing restarts the sandbox. If a tool is missing, the model says which profile has it. A value that is not a profile ID is ignored.

---
name: cut-clips
description: Cut a video into clips with ffmpeg.
sandbox: media
---

When the folder of a skill holds other files, such as references and scripts, the answer starts with Base directory for this skill: and the folder, and names up to 20 of the files, relative to it, so the model reads them with read_file. A sub-agent that has no read_file gets the instructions only. A skill with requires: [exec] in a chat that cannot run commands answers that it cannot be used there. Every chat with at least one skill has load_skill, and a sub-agent gets it with its parent’s other tools. It has no switch and Settings > Tools does not list it; the Skills menu chooses what it offers. The Sandbox does not see the skill folders (the built-in bash does, see Commands on this machine). When the model reads a SKILL.md with read_file at a wrong path, the error names the right path and load_skill. A SKILL.md over 64 KiB is refused.

Skills come from six places, nearest first, and the nearest wins when two have the same name:

The agent layer holds the skills of one saved agent. Only a chat that runs that agent sees them, and it needs no grant in the agent’s skill list. They win over your personal skill of the same name, for that agent only. An agent writes one by a change proposal of kind skill with scope agent (see Agents); nothing is written until you confirm, and the write can be undone. An agent skill cannot take the name of a built-in skill or of a document skill such as xlsx, and a skill that you locked in your personal layer stays locked against it. The grant skills.write shows the built-in writing-skills to the agent, led by the line “Do not write files. Call propose_change with kind skill.” The Skills page lists agent skills with the agent’s name and a Remove button; a removed skill goes to the Trash. GET /api/chats/skills?agents=true adds them to the list with layer: "agent", agent and agent_name (a chat’s own list has the layer of its agent already), and GET or DELETE /api/chats/skills/agent/<name>?agent=<id> reads or removes one.

The add-on layer holds the skills of the add-ons that the chat can use now: installed, running, usable by you and on for the chat (see Add-on tools). A chat with a saved agent gets them only for the add-ons the agent grants. The model loads one by its name with load_skill; its files are in /workspace/shared-addon-skills/<add-on>/<skill>/, where the add-on ID says where it comes from. Switching the add-on off for a chat takes its skills out of that chat’s index, and the skill list shows each one with addon and addon_title. Its switch id is addon:<name>.

An add-on can also replace a built-in skill of the same name, for example the Office add-on’s own xlsx, written for its tools. The add-on’s skill then serves and the built-in one shows shadowed: "addon" with shadowed_by, the add-on’s ID. When the add-on is off for the chat or not running, or you switch its skill off (addon:xlsx), the built-in skill serves again: the model is told in one line, and the built-in skill in the skill list carries fallback, the add-on’s title. When several add-ons replace one skill, the one installed first serves until an administrator chooses another in Settings > Tools, under Skills that add-ons replace, or with the switch in the add-on’s details on the Add-ons page.

In the Skills menu over the message box each skill says where it comes from: Built-in, the add-on’s title, Personal, Shared or Workspace. A built-in skill that an add-on replaces is listed under the others, dimmed, with “Replaced by ” and no switch. When a built-in skill serves because the add-on’s own skill is off or not running, one line under the title says so. The Skills page lists add-on skills under the Add-on layer, with the add-on’s title as the badge, and says which skill replaces which. See Skills of an add-on for how an add-on ships them.

The format is the same as the skills LocalAI already used, so an existing skill carries over by copying its folder into one of the places above. Skills in the public Agent Skills format can also be imported from a zip file and exported as one (see Import and export skills). Git sources are not part of chats.

curl -X POST .../api/chats/skills -d '{"layer": "personal", "name": "review", "description": "Check a change before it ships", "body": "Read the diff.\nSay what you find."}'
curl .../api/chats/skills?chat=3f1c...            # what the chat has, with its switches
curl -X PUT .../api/chats/3f1c.../skills -d '{"off": ["review"]}'   # switch one off for this chat

A chat keeps its own switches. Turning a skill off takes it out of the index at the next turn. A switch with the plain name turns off the skill that wins, so a skill of the same name further away shows through, as the list says. A switch with the id layer:name (the id in the skill list, for example personal:review) turns off the skill of that layer only. A deleted skill goes to the Trash like any file. Only an administrator writes shared skills, and everyone reads them. Your personal skills are as private as your files.

The Skills page lists them by layer and edits personal skills, and the Skills menu over the message box switches them per chat. The menu has one switch for each skill, with its name and a line of its description (the full text shows as a tooltip), the count of skills that are on (“12 of 20 on”), and Select all and Disable all. From nine skills on it also has a search field; while a search is on, the two buttons read Select shown and Disable shown and change only the skills in the list. Every change is one request, and a change the server refuses goes back with a message under the list.

A chat stores the skills that are off, not the skills that are on. So Select all sends an empty list, Disable all sends the ids of every skill in the list, and a skill you add later is on in every chat, also in a chat where you chose Disable all. The menu says so under its title.

The server ships these built-in skills: writing-skills, localai-workspace, localai-apps, localai, assemble-media and media-prompting. localai teaches the model the LocalAI client tools: when to use each one, how to clone a voice and what to say when a model is missing or a permission is refused. A chat lists it only while it has the LocalAI client group, so it costs nothing when the group is off. An add-on cannot replace it, as for the other skills that describe LocalAI itself. An administrator’s chat that has the LocalAI admin group also lists one skill per admin recipe, named localai-admin-<recipe>, such as localai-admin-install-chat-model. Nobody else sees them. See the prompt and the recipes. localai-workspace describes changes to your persona, profile, shortcuts, Home widgets, and theme; see Make LocalAI yours. localai-apps describes how to build an app, tracker, or tool as a Page. assemble-media is for the sandbox. It has tested ffmpeg, sox and ImageMagick recipes to join, trim, mix, subtitle and inspect generated pieces, and to make frames and inpainting masks for the next generation. It can also make a simple video from frames drawn with Python or SVG. It carries a hint for the media sandbox profile. media-prompting teaches the model how to prompt the image, video, music and speech models: a loop of pick, read the card, generate, inspect and change one thing, the anatomy of a prompt for each kind, what steps, guidance, size and seed do, and what to refuse. It has one card per model family in its cards/ folder (Qwen-Image, MiniMax-H3, YuE2 and Qwen3-TTS), which the model reads when it uses that family. To add a family, add a card and a row in the table of SKILL.md.

Import and export skills

LocalAI reads skills in the public Agent Skills format: a folder with a SKILL.md (frontmatter with name and description, and the optional license, compatibility, metadata and allowed-tools) and, optionally, scripts/, references/ and assets/. On the Skills page, Import takes a zip file and Export (on one of your personal skills) gives one back. Imported skills go to your personal layer, as with POST /api/chats/skills/import.

The zip holds either one skill (SKILL.md at the top) or one folder per skill. The server checks the whole archive first and stores nothing when any part is not valid:

• name has 1 to 64 lowercase letters, digits and single hyphens, with no hyphen at the start or the end, and equals the folder name. description has 1 to 1024 characters. compatibility has at most 500 characters. metadata maps text to text. LocalAI reads the names as ASCII only, which is stricter than the specification.
• A path with .., a leading /, a backslash or a drive letter, a link, a device, an encrypted entry, two names that differ only in case, and a file and a folder with one name are refused.
• At most 500 entries, 5 MiB for a file and 20 MiB in all, counted on the bytes that are really unpacked.
• The SKILL.md is at most 64 KiB, as for every skill. Fields that the specification does not name are kept in the file and ignored.

A name that you already use is refused with 409; an import never replaces a skill, so delete or rename the old one first. The name of a skill that ships with LocalAI (a built-in skill, a document skill such as xlsx) is refused with 400, so an imported file cannot take its place.

Scripts are stored, not run. The import writes every file, scripts/ included, as a plain file and runs nothing. A script is only read or run later, when a chat that has the tools for it chooses to, under the rules of that tool (see Running commands). Skill text is data from the person who wrote it: read an imported skill before you give it to an agent.

An imported skill is listed with new: true and a New badge until a chat loads it with load_skill for the first time. Use the mark to find skills you have not read yet. Editing a skill in the page writes only the name, the description and the text, so the other frontmatter fields of an imported skill are dropped; edit the file in Files to keep them.

curl -X POST .../api/chats/skills/import -F file=@pdf-tools.zip      # 201 with the stored skills
curl -o pdf-tools.zip .../api/chats/skills/personal/pdf-tools/export  # one folder, same layout

An export of a skill imports again to the same files.

Document skills

The familiar names docx, pptx, pdf, and xlsx identify document authoring skills from add-ons, not built-in skills. Sandbox supplies Python/Paper procedures and their references. Simple Office supplies separate procedures for its document tools, without command execution.

1. Install and enable a provider on the Add-ons page.
2. Switch the provider on in the chat’s Tools menu.
3. For a saved agent, grant that add-on explicitly and select the required skill names.
4. For Sandbox procedures, select Sandbox for bash and allow command execution in the chat or agent.

Sandbox procedures require usable isolated commands from the selected Sandbox provider. An installed Sandbox or a host command runner alone is not enough. These selections never grant add-ons or command execution automatically.

With both providers eligible, the existing provider choice in Settings > Tools applies. Without a choice, the eligible provider installed first serves each name. A pinned provider that is unavailable does not switch silently to another provider. The Skills menu shows its unavailable reason. Folder, personal, and shared skills keep their existing precedence over add-on skills.

With neither provider eligible, LocalAI offers no built-in document authoring fallback. Document-text extraction and the read_file and search_files tools remain available independently of these authoring skills.

Existing saved agent selections keep the same names. Existing builtin:docx, builtin:pptx, builtin:pdf, and builtin:xlsx OFF preferences become corresponding addon:<name> OFF preferences. LocalAI persists this change before selecting providers. Existing add-on and plain-name OFF preferences remain effective. You can explicitly switch a skill on again; subsequent reads do not turn it off again. Other skill preferences remain unchanged.

Sandbox installs PDF helpers inside its guest: /usr/local/lib/localai/document-skills/pdf/content_qa.py and /usr/local/lib/localai/document-skills/pdf/verify_pdf.py. Run them with python3 through Sandbox commands, not through paths in host skill folders. Upgrades remove stale built-in document trees, but preserve user-written skills. Use load_skill by name; historical physical paths are not a compatibility interface.

Web

A chat can search the web with web_search and read a page with web_fetch. LocalAI serves both itself, with no add-on and no key, and they are on by default. They only read. Every result is labelled as untrusted content from the internet, and web_fetch refuses addresses inside your network. An administrator can switch each tool off, set a SearXNG instance for the searches and allow more ports in Settings > Tools. An add-on can replace either tool by name: the optional Web add-on replaces both, to search with Brave Search, Tavily or Google with a key and to read PDF files. See Search the web in chats.

Collections

When you may use collections, a chat has two more tools: list_collections and search_collection (collection, query, limit). They search your own collections, the ones of the Knowledge page, and nobody else’s: a name that is not yours is answered “collection not found”. An answer holds at most 20 passages and about 16 KiB. A sub-agent gets these tools only when its parent names them.

Add-on tools

A chat can use the tools of the add-ons you may use. The Tools menu of the chat lists them with a switch for each add-on; a switch applies to that chat from its next turn. A tool runs as you, in your chat, and never as a user a model names.

• A tool that only reads gives the model its result.
• A tool that changes an add-on’s data (rows, a schema, a new database, a job) changes it at once. Turning an add-on on for a chat or an agent is your consent, so there is no confirmation card. The model is told what was changed and whether it can be undone, and the tool entry in the chat says the same. Undo is the safety net, so a change the add-on kept a change set for shows an Undo button on its entry: Tables keeps one for every row and schema change and for a new database, and Fine-tuning and Quantization keep one for a job start (an undo stops the job while it runs). After you press it the entry says “Undone”, or why it could not be: the data changed after the change (undoing would overwrite later work, and nothing is changed), the change is older than 7 days, or the job already finished. Only you can press it: the model is told the change can be undone but has no tool for it, and an API key cannot call it. Some changes keep no change set, such as one whose data was too large to keep, stopping a job or exporting a model; their entry says “This cannot be undone” and gives the reason. The file changes of a sandbox or an Office document are different: they are one change in the history of your files and you can undo them there. Reads and changes use your own permissions, and a change on data that moved since it was read is refused, not applied. A scheduled or file-triggered run uses the same rule, but a run with no agent gets no tool that changes anything: name the add-on in an agent to allow it.
• An action tool, such as running a command in a sandbox, runs at once and only in a chat. No other place that offers add-on tools (the OpenAI-compatible API, MCP, agents) lists or runs one.
• A sub-agent gets the add-on tools its parent names, or all of the parent’s tools when the parent names none.

curl -s localhost:8080/api/chats/$ID/addons
# {"addons":[{"id":"office","tools":4,"off":false}]}
curl -s -X PUT localhost:8080/api/chats/$ID/addons -d '{"off":["office"]}'

Metrics

With metrics on, /metrics counts every turn of the loop (a chat in the page, a saved agent, a trigger run, a connector message and an agent job):

They keep the names the old agent pool had, so an existing dashboard works. The origin label is new.

Who can see a chat

A chat belongs to the user who started it. Another user’s chat id always answers 404. Requests made on the user’s behalf go through the same model access rules and quotas as a direct request to /v1/chat/completions.

With authentication off, chats belong to one anonymous owner.

Memory settings

Your settings page (Account) has a Memory tab. It lists the notes that the host puts in the prompt of your chats (Memory is built in, and another add-on can declare context files): your own index and its topic files, the notes of each saved agent and of each connector conversation, and the agent profiles. Each index shows its size against the caps (at most 40 lines and 2 KiB for an index, 4 KiB for a profile, 6 KiB of notes in one turn). You can open a file, edit it, delete it (it goes to the Trash) or clear all of them. An index cannot be saved over its cap. A model changes these files only through a confirmed change proposal.

GET /api/chats/context-files returns the list for the page: limits, and groups of {source, scope, key, max_bytes, max_lines, files[]}. It only reads. The page edits and deletes with the Files API.

Your files

Each user has a personal workspace: folders at any depth, uploads, a Trash and a history with undo. Paths in the API are inside your own home folder, which is /. You cannot name another user’s files, and a path with .. is refused.

curl -X POST ".../api/chats/files/folders" -d '{"path": "/Reports"}'  # make a folder
curl -X PUT  ".../api/chats/files/content?path=/Reports/q1.txt" --data-binary @q1.txt
curl         ".../api/chats/files?path=/Reports"                    # list a folder
curl         ".../api/chats/files/content?path=/Reports/q1.txt"     # download
curl -X POST ".../api/chats/files/move" -d '{"from": "/Reports/q1.txt", "to": "/Archive/q1.txt"}'
curl -X DELETE ".../api/chats/files?path=/Archive"                  # to the Trash
curl         ".../api/chats/files/trash"                            # what can be restored
curl -X POST ".../api/chats/files/undo" -d '{"rev": 12}'            # restore it
curl         ".../api/chats/files/history?path=/Reports&limit=50"   # the changes, newest first (at most 200)
curl -X DELETE ".../api/chats/files/trash/12"                       # delete that one for good
curl -X DELETE ".../api/chats/files/trash"                          # empty the Trash for good
curl         ".../api/chats/files/preview?path=/Reports/budget.xlsx" # what a workbook holds

• Nothing is erased, until you say so. A delete goes to the Trash, and undo restores it as a new change. A change you made after the deletion that conflicts with the restore makes it answer 409; with skip_conflicts the rest is restored.
• Emptying the Trash. DELETE /api/chats/files/trash deletes everything in your Trash for good, and DELETE /api/chats/files/trash/{rev} deletes one entry, the rev that GET /api/chats/files/trash lists. Both answer {"files": 2, "folders": 1, "bytes": 4096}, what they removed. The list gives the same three numbers for each entry, and totals for the whole Trash, also what a long list leaves out. A permanent delete removes the files and folders, their older versions and their entries in the history, and frees the space the bytes held a couple of minutes later, unless another file shares the same bytes. It works the same on a server with a database, also with several frontends on one database, and on one with the JSON index. It cannot be undone: undo of that change answers 404. It touches only your own Trash; a rev that is not in it is 404. The file tools of a chat cannot do this, only you can.
• Two uploads, one name. An upload replaces a file only when it says which version it started from (base). Otherwise both are kept, and the new one is named name (from you).ext; the answer says so in conflict_of.
• Downloads are safe. Files are served as downloads. With inline=1 an image, PDF, plain text, audio or video is shown by the browser; anything else, HTML and SVG included, never runs as a page.
• Attachments. Send a message as multipart/form-data with a text field and files. The files are saved in the chat’s own folder under Chats/ and the model gets their paths after your text. With a turn running the files are saved at once and the message waits like any other; the model reads them by path when the message reaches it. A sandbox that started before the files arrived sees them from the next turn.
• Attachments in the transcript. The transcript keeps your text and your files apart. In GET /api/chats/{id}/messages a user line has text, the words you typed, and attachments: path (inside your home, for the files API), name, size, mime, version, and missing when the file is no longer in your files. A file whose chat folder was renamed gets its new path. A waiting message has the same two fields. The list of paths and the text read from the files go to the model only: the chat shows an image as a thumbnail and any other file as a chip with its size and a download link, and a click or Enter opens the file in the chat’s files pane. Messages sent before this change are shown the same way.
• Previews of documents. GET /api/chats/files/preview?path= reads what a .xlsx, .xlsm, .csv, .tsv, .docx or .pptx file holds, for the preview pane of a chat and the Files page. A spreadsheet gives {"kind": "table", "sheets": [{"name", "rows", "total_rows", "total_cols"}]}: every sheet, the first 200 rows and 30 columns of each as text, with dates, booleans and the stored result of formulas. A Word document gives {"kind": "document", "blocks": [{"type": "heading" | "item" | "paragraph", "level", "text"}]} and a presentation {"kind": "slides", "slides": [{"n", "title", "lines", "notes"}]}; both keep at most 200 000 characters and set truncated when they cut. The formatting is not kept. The path rules are those of the download. A file over 20 MiB answers 413, another type 415, and a file that is not what its name says 422. Each frontend keeps the recent answers in memory, by the content of the file: a new version is a new entry, so frontends of a cluster never disagree, and nothing is shared between them.
• Search. GET /api/chats/files/search?q=budget finds files by name, lines inside text files, and lines of the text of PDF, Word, Excel and PowerPoint files, ignoring case. A hit inside a document has document: true and its page, sheet or slide; indexing counts the documents whose text is still being read. Text files are read on each search: one over 1 MiB, and any other binary file, is found by name only, and a very large workspace is scanned up to a limit. See Search inside documents.
• The model can use your files. A chat with files on gives the model one set of file tools: list_files, read_file, write_file, edit_file, move_file, delete_file and search_files. They are the same with or without the Sandbox. What they change is listed in the history as an agent change of that chat, and you can undo it from the note under the call; a delete goes to the Trash. A sub-agent gets the file tools of its parent chat (or the ones its parent names).
  • Paths. /workspace/home/<path>, home/<path> and /<path> all name <path> in your home folder. /workspace/shared-<name>/... is a shared folder, read-only when it is shared with you for reading, and /workspace/shared-skills/..., /workspace/shared-builtin-skills/... and /workspace/shared-addon-skills/... are the shared, built-in and add-on skills, read-only. Any other path under /workspace is refused with the right spelling, and nothing is written: an app the model builds goes to a Page, /workspace/home/pages/<name>/index.html.
  • read_file reads lines offset to offset+limit-1 (at most 2000 lines, text files up to 4 MiB). On a PDF, Word, Excel or PowerPoint file it reads the text of the document, with a ## Page N, ## Sheet or ## Slide N line where each one starts.
  • edit_file replaces old_string with new_string. old_string must match exactly once, unless replace_all is true; no match and several matches are errors that say what to do. Text files up to 8 MiB. When the file changed while it was edited, the edit is saved as a copy next to it.
  • list_files lists one folder, or with pattern every path below the folder that matches it: * matches any characters including /, ? one character, [...] a class. At most 500 paths.
  • search_files finds plain text in names, inside text files and inside the text of PDF, Word, Excel and PowerPoint files (at most 30 hits). With regex: true, query is a regular expression (the extended syntax of grep -E) matched against each line (at most 200 lines). Case does not matter unless ignore_case is false. path may be a file or a folder. A hit in a document reads path (page 3, line 40): text, with sheet "Name" or slide N for a workbook or a deck; the line is the offset to give read_file. When documents below the path are still being indexed, the answer says so with the full count (2 files are still being indexed), so the model searches again instead of concluding that nothing matches. A search looks at 20 000 files and folders and reads 64 MiB of text at most; when it stops at one of these limits before the end, the answer ends with [results limited: ...], the REST search sets limited, and the Files page says “Results limited”, so a missing match is not taken as proof.
• Pictures and recordings. describe_image lets the model look at an image in your files and transcribe_audio turns a recording into text. A voice note attached to a message is transcribed on the way in and its transcript goes with your message; the file is kept as it is. They use helper models, which you choose in the settings (Chat image model, Chat transcription model). Left empty, describe_image uses the chat’s own model when it can see images, and otherwise the first installed model that can see images (or, for audio, transcribe). If there is none, a cloud-proxy chat model that does not declare vision is tried as a last resort. With none installed the tool says what to install. The helpers run as you, so your model access and quota apply.
• A file is at most 256 MiB. Uploads of the Files page do not use the general upload limit (15 MB by default). They are limited by this size, unless you set --upload-limit (LOCALAI_UPLOAD_LIMIT) yourself: then your value applies to them too, and an upload is at most the smaller of the two. A folder listing reports the limit in force in max_file_size (bytes), and each entry has modified, when it last changed. A message with attachments is limited to 1 GiB in all, and each attached file to 256 MiB. A message with attachments does not use the general upload limit either, unless you set --upload-limit: then a message is at most the smaller of your value and 1 GiB. A message without attachments (JSON) always uses the general upload limit.

Search inside documents

When a PDF, Word (.docx), Excel (.xlsx, .xlsm) or PowerPoint (.pptx) file is uploaded, written by a chat, synced from a Sandbox or restored, the server reads its text in the background, usually within a few seconds. The file search of the Files page and the chats’ search_files then find the document by what it says, even when its name is a random string.

• What is read. The text layer of a PDF, page by page; the cells of each sheet; the headings, paragraphs and tables of a Word document; the slides and their notes. A scanned PDF has no text layer, so it is skipped (no OCR in this version). At most 50 MiB of file, 200 pages and chats_index_max_text_bytes of text (2 MiB by default) are kept for one file; a file over a limit is cut or skipped. A file whose content does not match its type (a .pdf that is not a PDF) is skipped.
• Where the text is kept. In the server’s own store, next to the index of the files: the auth database (SQLite or PostgreSQL) when there is one, otherwise a textindex folder under the chats’ data folder. The text never becomes a file in anybody’s folders, and it is not sent anywhere.
• Who finds it. The text follows the permissions of its file: each hit is checked against the file at search time, so only users who can read the file find it, in their home or in a shared folder. A file that moved or changed since it was read is not shown until it is read again. Deleting a file removes its text; emptying the Trash removes what is left. The text of what a purge erased is dropped right after it, and when that cannot finish (the server stops, the database fails), the indexer finds the entries whose file is gone on its own: while Search inside documents is on, every 30 seconds it checks 200 entries, round all of them.
• Search engine. On SQLite the index uses FTS5 with the trigram tokenizer, on PostgreSQL a pg_trgm index when the extension can be created; otherwise, and with the JSON store, the server scans the stored texts. The answers are the same: case-insensitive text, or a regular expression matched line by line.
• Settings. Search inside documents (chats_index_files, on by default) and Text kept per document (chats_index_max_text_bytes) in Settings > Tools. With the switch off nothing new is read; text read before is still used for files that did not change.
• Reading a long document. The index keeps the first chats_index_max_text_bytes of a document. When read_file needs more, it reads the whole file once and keeps its whole text (up to 16 MiB of characters) in the same store, by the content of the file, so the next pages come from there and not from the file again. A new version of the file is new content and is read again. The kept text goes with the file’s index entry: deleting the file or emptying the Trash removes it too.
• Existing files. At its first start the indexer reads the files that are already there, in steps, and goes on where it stopped after a restart.
• Distributed mode. Single-runner: one frontend at a time reads files, under an advisory lock, and the text is in the shared database, so every frontend searches the same text. An upload on any frontend is queued in the database at once, so its search says the file is being indexed. A chat worker searches the text but never reads files for the index. The whole texts that read_file keeps are in the shared database too, so a long document is read once for every frontend. Where the check for entries of erased files stands is in the memory of the frontend that runs the pass: another frontend that wins the lock checks from its own place, which only repeats work.

The Files page

The Files page in the sidebar is a file browser for all of this.

• Browse. A breadcrumb shows where you are; a deep path folds its middle into a menu. Folders come first. Click a column (Name, Modified, Type, Size) to sort by it, and again to reverse it. List shows a table; Thumbnails shows tiles with a picture of each image. The page remembers the view and the sort in your browser. Dates read as “5 minutes ago” or “yesterday”; hold the pointer on one for the full date. Back and Forward of the browser go between folders.
• Filter and search. Typing in the box filters the open folder by name. Press Enter, or choose Search all files, to search the names and the text of every file.
• Upload. Use Upload (its arrow also uploads a whole folder), drop files or folders anywhere on the page, or paste with Ctrl+V; a pasted screenshot gets the date and time as its name. A drop on a folder row, or on a folder of the breadcrumb, uploads into that folder. The upload panel at the bottom right shows each file with its progress, speed and time left, and the total for all of them. You can cancel a file, try a failed one again (the panel says why it failed), and keep working: an upload keeps going when you open another folder or another page of the app, and the browser asks before you close the tab while files are still on their way. A file over the server’s limit is refused before it is sent. When an upload has the name of a file that is in the folder already, the page asks: Replace it, Keep both (the new one gets a new name) or Skip it.
• Select. Click a row to select it, Ctrl-click (Cmd on a Mac) to add one, Shift-click for a range, or use the boxes. The bar above the list then offers Download, Move to… and Move to Trash for the selection.
• Act. Each row has a menu (⋮, or a right click): Preview or Open, Download, Rename, Extract here (on an archive; see Extract an archive), Move to… and Move to Trash. A folder of your own also has Share… when the server has accounts (see Share a folder of your home). Drag rows onto a folder to move them there. New folder and New file add one in place, with a name you can type over. A move, a rename and a delete show a message with Undo.
• Keyboard. Arrows move between rows (and tiles), Shift+arrows extend the selection, Space selects, Enter opens, F2 renames, Delete moves to the Trash, Ctrl+A selects all, Escape clears the selection, Backspace opens the parent folder, and typing the start of a name jumps to it.
• Preview. Opening a file shows it in a side pane, the same views as the preview pane of a chat, with Download, Rename, Move to… and Move to Trash. On a phone it is a sheet from the bottom. Escape closes it.
• Trash and History. The Trash tab restores what you deleted, deletes one item for good, or empties the Trash; each of those asks first and says how many files and how much space it removes, and Empty Trash is off while the Trash is empty. The History tab undoes a change of the open folder.

LocalAI keeps two folders of your home for itself: LocalAI/, the settings it reads (persona, profile, shortcuts, Home, theme; see Make LocalAI yours), and Chats/, one folder per chat. Files lists your own files first and these two last, under Managed by LocalAI; the list API marks them with managed (localai or chats). Moving one to the Trash or renaming it asks first and says what stops working.

Extract an archive

Choose Extract here in the menu of an archive on the Files page to unpack it. For a large archive this is the best way: the server does the work and no chat is needed. The same call is POST /api/chats/files/extract {"path": "/report.zip"}. Add "dest": "/some/folder" to choose the folder.

• Formats. ZIP, TAR, and TAR with gzip, bzip2, xz, zstd, brotli, lz4 or snappy (.tar.gz, .tgz, .tar.bz2, .tar.xz, .tar.zst and so on). 7z and RAR are off by default; see 7z and RAR. A single compressed file, such as notes.txt.gz, is not an archive and is refused.
• Where the files go. By default into a new folder next to the archive, named like it without the extension: report.zip and report.tar.gz both give report/. When that name is taken, the folder is report 2, report 3 and so on. With dest, the files go into that folder, which is created when it is missing. A folder that LocalAI manages (LocalAI, Chats, Memory, pages, .skills) is refused.
• One change. All files are written as one change, so one Undo removes the whole extraction. The toast that shows the result has the Undo button. The change is also in the History tab.
• A name that is taken. An existing file is never replaced. The new file is saved next to it as a copy named name (from <user>).ext, and the answer lists it under conflicts. A file with the same content as the existing one is not written again.
• What is skipped. Symbolic links, hard links, devices, sockets and pipes are not extracted. A name that is not valid UTF-8, a name that the Files page does not allow, a path deeper than 64 levels, a repeated name, an encrypted ZIP entry and a file over 256 MiB are skipped too. The answer lists them under skipped with a reason. A nested archive is written as a plain file; it is not unpacked.
• Paths that leave the folder. An entry with an absolute path, a .. part or a NUL byte makes the whole archive refused with a 400 error, and nothing is written. A backslash in a name counts as a folder separator.
• Limits. The limits are counted on the bytes that are really read, not on the sizes that the archive says. They are: most bytes in all files (1 GiB by default), most entries (20,000 by default), 256 MiB for one file, a ratio of 1,000 between the expanded size and the size read (checked after 64 MiB), and 10 minutes. An archive over a limit writes nothing and the answer says which limit it was (413, or 408 for the time). An administrator sets the first two in Settings > Tools (chats_extract_max_bytes and chats_extract_max_entries, see Runtime settings).
• Names with other encodings. A ZIP made by an old tool may store names in a local code page. Those names are not valid UTF-8, so they are skipped and listed. Extract such an archive in a chat sandbox with a tool that knows the code page.

The model has no tool for this on purpose: a tool would cost tokens in every chat. A chat can unpack a small archive in its sandbox. The localai skill tells the model to point you to the Files page for a large one.

7z and RAR (risk)

The readers for 7z and RAR run inside the LocalAI server. They take sizes from the file and allocate memory for them before they read any data, and they have no memory limit. A crafted 7z or RAR file can make the server run out of memory and stop. For this reason they are off by default. An administrator can turn them on with Extract: allow 7z and RAR (chats_extract_7z_rar). Do this only when you trust every user who can upload files. The byte, entry, time and ratio limits still apply, but they cannot stop an allocation that happens before the first byte is read. ZIP and TAR are not affected: the ZIP entry count is read from the end of the file and checked before the reader loads the directory, and the zstd and xz readers have a fixed memory cap.

Your own rules: AGENTS.md

Put an AGENTS.md file in a folder to give the assistant rules for that folder: how to name files, which language to write in, what not to touch. LocalAI never sends the text of the file to the model. It sends one line that points at it, and the model reads the file with its file tools:

Rules for this folder are in /workspace/home/Reports/AGENTS.md. Read that file before you start.

• At the start of each turn, the line names the AGENTS.md of the chat’s own folder (Chats/<chat>/), of the folders above it, and of your home, nearest first, two at most. It is part of the note of the turn, not of the system prompt, so it costs about 25 tokens a file and only when such a file exists.
• The first time in a turn that a file tool (list_files, read_file, write_file, move_file) works in a folder whose AGENTS.md, or the one of a folder above it, was not named yet, the same line is added to the result of that call. Each file is named once a turn. Reading the AGENTS.md itself counts.
• A trigger run already gets the rules of its folder and the folders above it in its first message, so it gets no line for them.
• The checks run as you, on the shared workspace, and keep nothing between turns, so they work the same with several frontends.

A folder pages/<name>/ with an index.html is a page: the UI shows it in a sandboxed frame under Pages. See Pages.

Shared folders

A shared folder is a folder that several users use. An administrator creates it and chooses its members: a user, or Everyone (every user, also the ones who sign up later), each with Can read or Can edit. A member’s chats see the folder at /workspace/shared-<name> (read-only for a reader), and its pages show on the Pages screen under Shared with you (see Shared pages). A user who is not a member sees nothing of the folder: every call about it answers 404, as for a folder that does not exist.

In the UI, the Shared tab of Files lists the folders. An administrator creates, renames and removes them there, and opens Members to add a person or Everyone, change their access or take it away. Any other user sees the folders shared with them and their access.

• Where it lives. A shared folder is /shared/<name> in the workspace, outside every home folder. A name has 1 to 64 letters, digits, spaces, dots, dashes or underscores, starts with a letter or a digit, and is unique without regard to case. A server keeps at most 100 shared folders, with at most 200 members each. A new folder has an empty pages folder, and the administrator who creates it is a member who can edit it, so they can fill it. Remove them when they do not need it.
• Access is a grant. A member is a workspace grant on the folder and everything in it, checked on every call. A change applies at once to the Files and Pages screens and to the shared pages’ bridge; an open chat sees it the next time it opens.
• Rename keeps the members, the pages and the consents to them.
• Remove moves the folder and its files to the Trash as one change, and answers with undo_rev. Undo (or POST .../restore with that rev) brings it back with its members. Nothing is erased. Removing a folder also drops every user’s consent to its pages, so a restored page asks again before it runs.
• Audit. Every change (create, rename, delete, restore, grant, revoke) is written with who made it and when: in the table studio_shared_folder_events of the auth database, or in chats/shared-folders/audit.json under the data path, and in the log. A change that the LocalAI Assistant made is written as @assistant.

# Create a folder, share it with everyone (read) and with one person (edit).
curl -X POST ".../api/chats/admin/shared-folders" -d '{"name": "Team"}'
# {"id":42,"name":"Team","path":"/shared/Team","pages":0,
#  "members":[{"principal":"<your id>","name":"Ada","mode":"write"}]}
curl -X PUT ".../api/chats/admin/shared-folders/42/members/%40everyone" -d '{"mode": "read"}'
curl -X PUT ".../api/chats/admin/shared-folders/42/members/marta@example.com" -d '{"mode": "write"}'
# Remove it, then bring it back.
curl -X DELETE ".../api/chats/admin/shared-folders/42"          # {"folder":{...},"undo_rev":118}
curl -X POST ".../api/chats/admin/shared-folders/restore" -d '{"rev": 118}'

The LocalAI Assistant has the same operations as tools (see LocalAI Assistant). In a cluster the folders and the grants live in the shared workspace database and the audit in the auth database, so every frontend sees the same state.

Share a folder of your home

You can share a folder of your own home with other people, without an administrator. Open Files, choose Share… in the menu of a folder, and add a person or Everyone, with Can read or Can edit. This is the same Share dialog as for agents and the other things you can share (see Share with your team).

• What you can share. A folder inside your home: not the home itself, and not a folder that LocalAI keeps or reads as your own words: LocalAI/, Chats/, Memory/, pages/, a .skills folder anywhere, or a folder inside one of them. You cannot share a folder that someone shared with you or an administrator’s shared folder. A person shares at most 100 folders, each with at most 200 grants.
• What your chats use. Your chats load your skills, your notes, your agent profiles and your persona, and Pages runs your pages, with your own rights. LocalAI leaves out anything in a folder on which another person, or Everyone, can edit: a .skills folder inside a folder you share with Can edit gives your chats no skill, and a page or a note there is not yours. What you share with Can read stays in use. The others still see and change those files as files.
• Who. An active account that the search finds, or Everyone (every account, also the ones created later). The search is the user picker of the other kinds of sharing (see Share with your team): it starts at three characters of the display name, a part of an address finds nobody, and an account without a name is found by its whole address only. It shows a name and nothing else.
• What they see. The folder is in their Shared tab with your name and their access, and their chats see it at /workspace/shared-<name> like an administrator’s shared folder (shared-<name> 2 when two have the same name). Its path in your home is not shown to them. Its pages/ are not shared pages: a page runs in the browser of the person who opens it, so only an administrator’s shared folder can share one.
• Taking it back. A lower access or a removed grant holds from their next file call, on every frontend. Their chats that run with the folder on the frontend that serves your change are stopped before the change answers; the other frontends get the request on the chat bus and stop theirs within seconds. A grant follows the folder: when you rename or move it inside your home, it stays shared; when you move it to the Trash, nobody else can open it, and restoring it from the Trash shares it again.
• Moves that keep a share where it does not belong. A folder that is shared, or that has a shared folder inside it, cannot move into another person’s home (also not by someone who can edit there), out of a home, or into LocalAI/, Chats/, Memory/, pages/ or a .skills folder. The move is refused with 409 and type folder_shared, and nothing moves: stop sharing it first. A folder of your home that still has a grant from before, wherever it is, is in your list of shared folders and you can remove its grants.
• Only from your browser. Changing who has a folder, listing it and the search accept only your own signed-in browser tab. An API key, an agent, a tool and an MCP client cannot share anything. In local-owner mode (no accounts) folders cannot be shared.
• Audit. Each grant and revoke is a line of the shared folders audit, with you as the one who made it.

“Browser only” means a same-origin fetch with the header X-LocalAI-Confirm equal to the folder ID, no API key and no tool, agent or MCP marker; anything else gets 403. A folder you cannot share, one that does not exist and one of someone else get the same 403, so a call cannot tell them apart.

The grants are the same workspace grants as an administrator’s, in the workspace database, and nothing else keeps a copy: every frontend reads them on every call, so a change made through one frontend holds at once on all of them. A frontend stops its own running chats, and sends the request to stop on the chat bus to the other frontends and chat workers, which stop theirs. The search answers on the frontend that serves the call and keeps the count of searches of each person in the memory of that frontend (per instance): with several frontends a person may search at that rate on each of them, and a restart resets the count. The count only slows down a person who tries many names; it decides no access.

Files need a place to live. The choice is made at start and is explicit: with a database the tree goes there, and without one it goes in a JSON index.

The JSON index is a plain folder: index.json is a snapshot and index.log is the changes since, one record per line. A change is written and synced before the call returns, a start replays the log and drops a last record that a crash cut short (the damaged log is kept next to it as index.log.damaged-<time>), and the log is folded into a new snapshot when it passes 16 MiB. Files, uploads, attachments, skills, the Trash, undo and the limits behave as they do on a database, because both stores pass the same test suite. One LocalAI process owns that folder, because its lock lives in the process: a second process on the same folder would overwrite the first one’s index, so use a database when more than one frontend serves the files. There is no move between the two indexes: files kept in a JSON index are not copied into a database when you turn authentication on, and the other way round. Copy them with the files API.

When files are off, every files route and every attachment answers 409 with the reason, the list endpoint returns "files": false and files_reason, and everything else in the chats works. A chat then has no skills either, not even the built-in ones, and no load_skill: skills are files, and every built-in skill works on files or runs commands.

In a cluster, configured S3 holds workspace bytes; the distributed compose example sets it up with Garage. Without S3, Files uses the existing DataPath/chats/blobs directly. All Files participants must then mount the same backing data directory and use the same PostgreSQL metadata database. See Shared filesystem for Files for the operator contract. With PostgreSQL, startup checks that every node sees the same blob folder and stops with an error when it does not.

Storage

When chats live in memory, the chat page says so, and the list endpoint returns "persistent": false.

If a server stops in the middle of a model request, the turn ends as interrupted. A message you sent while that turn ran and that the request had already taken is waiting again, and “Send now” starts it.

A sub-agent conversation is read-only: it runs with the tools its parent chose, and a message to it answers 409.

The JSON files are for one LocalAI process. A cluster needs PostgreSQL, as distributed mode already does.

Clusters

In distributed mode any frontend can serve any request about any chat.

State mode: shared. Chats, their messages, the waiting messages and the claim that lets one turn run at a time live in PostgreSQL. Live events travel over the message bus, so a client connected to one frontend sees a turn that another frontend runs. Events are delivered at most once. The ring of recent events that serves a reconnect is per instance, on purpose: it is a cache of the live tail on the frontend or chat worker that runs the turn, and the transcript is the record. The process that runs a turn records its instance id (LOCALAI_INSTANCE_ID) on the chat. A reconnect that reaches another frontend asks that process for the missed events over the message bus (request and reply on chats.replay.<instance>), in replies of at most 512 KiB. When that process is gone, does not answer in 2 seconds, or no longer has the events, the client gets a resync and reads the transcript. The cap of 8 event streams per chat and user is per frontend.

Sub-agents. The runs are chats in the shared store, linked to their parent. The background limit, the list of runs and “stopping a chat stops its sub-agents” all read the store, so they hold when the turns of one chat run on different frontends. A stop reaches a run on another frontend over the bus. The tool subset of a running sub-agent is kept in the memory of the frontend that runs it, which is where it runs. A sub-agent started from a saved agent keeps nothing in memory (stateless): the agent is named on its chat record, and its tools are read from the store at each turn, as for any chat with an agent. The chat’s saved agents switch is stored with the chat, and the permission is checked again at each call, so every frontend gives the same answer.

Settings and edits. The settings, the title and the model of a chat, and the cut that regenerate and edit make, are stored with the chat. A change of title or model, a regenerate and an edit take the same turn claim as a message, so they are refused with 409 while a turn runs on any frontend. A video that comes with a message is held in the memory of the frontend that runs the turn, for that turn’s first request.

MCP connectors. The records of your MCP connectors are shared in PostgreSQL. The open MCP sessions are per instance: each frontend opens its own, and a local command (stdio) is refused in a cluster.

Where a turn runs. The frontend that wins the claim runs the whole turn. The model calls it makes are routed to inference nodes, and its MCP tool calls are sent to agent workers, exactly as for any other request. Agent workers do not run chats: they have no database.

From any frontend you can send a message, edit or cancel a waiting message, read the transcript, stop the turn and stream events. A stop travels over the bus to the frontend that runs the turn.

If a frontend dies. A running turn records a heartbeat every 15 seconds. One frontend, chosen by a PostgreSQL advisory lock, ends turns that have not beaten for a minute. Such a turn ends as interrupted, its waiting messages stay, and send-now starts them. A standalone process with a database does the same once at startup, for turns its previous run left behind. On a normal stop the server marks the turns it cuts short as interrupted itself, and it does not wait for them for good: closing the chats is bounded (15 seconds), and a turn that does not stop in time is marked interrupted in the database before the process exits, with its resume scheduled like a turn that died.

Resuming by itself. With --chats-auto-resume (LOCALAI_CHATS_AUTO_RESUME, off by default) the server goes on with an interrupted turn without anyone pressing Retry. The state lives in the chat’s row, so it survives a restart of any process: a count of tries, the time of the interruption and the time of the next try. The same frontend that ends stale turns checks for due resumes at each tick (30 seconds), and a chat worker takes the start when workers are on. The claim on the chat decides when two frontends race, or when a person presses Retry at the same moment: one turn starts. A turn is resumed at most 3 times, after 15 seconds, 1 minute and 5 minutes, and only within 30 minutes of the interruption. A new message from you starts a normal turn and the count begins again. While a resume is scheduled the chat reads will_resume: true (with resume_attempts) and the page waits instead of resuming too. A run of a trigger, a job or a loop stays running until the resumed turn ends, a goal stays active, and a failed run is reported only when the last try is spent. A chat that a messaging connection started is not resumed by the server: its reply is sent by the process that died, so the sender is told the turn was interrupted. A sub-agent chat is not resumed either; its parent decides.

Calls that a restart cut in two. The transcript is the checkpoint: each finished message and tool result is a line of its own. A call in flight has no result line, and running it again could do its work twice. So a call of a tool that may change something leaves an internal line before it runs (tool_intent: the tool name and the start of its arguments; the API never returns it). If the turn is resumed and an intent has no result after it, the model is told that those calls started, that it is not known whether they took effect, and to check the state before it repeats one. Only tools that only read skip the line: the add-on tools of kind read, the built-in tools declared read only, and a fixed list (the file, search, collection and web tools). A tool that nobody classified, such as an MCP tool, counts as one that may change something. A result is matched to an intent by the tool name, so two parallel calls of one tool can hide one unknown outcome. The effects that the host sends itself (the webhooks of a job, the notification of a run, the report of a trigger) do not repeat: each is sent when the run ends, behind its own once-only record, and the run ends only after the last try.

The answer that was being written. A message is stored as a line when it ends, so a process that is killed in the middle of a long answer would lose it. While a message streams, the server saves its text so far into the chat record every 2 seconds, or when 4 KiB of new text have come (not more than four times a second), and clears it when the line is stored. A message that ends in under 2 seconds writes nothing. When the next turn starts (a resume, or a new message of yours) a text that is still there becomes an assistant line, kept as it was when last saved, up to 128 KiB. A resume also tells the model where its message stopped, so that it goes on from there. A graceful stop does not need this: the turn that Close cuts short stores its text as it ends.

In terms of the distributed state rule: the resume state is shared (it is in the chat row), and the sweep is single-runner (the advisory lock of the reaper).

The JSON files are not supported in a cluster, as the Storage table says.

Saved agents

An agent is a saved set of instructions and tool grants that a chat can start with. See Saved agents, triggers and inbox.

The LocalAI assistant

An admin can start a chat that has the tools to manage the instance (install models and backends, edit model configs, check status). It starts from the Home page with /assistant, or over the API with assistant: true in POST /api/chats. It is an ordinary chat in the list after that. Only that chat has the tools, never its sub-agents. The chats_localai_admin setting turns the admin tools off. See LocalAI Assistant.

Chats in the web UI

The web UI talks to this API, so a chat keeps running when you close the tab and opens again from any browser.

• Home starts a chat. Home (/app) is the front door. Its message box is the one of the chat page, so everything a new chat offers works there before the chat exists:

  • pick the model (each row says whether it is loaded, what it can do and how it fits this machine) and a saved agent;
  • switch tools, add-ons and skills in the Tools and Skills menus. They are a draft: the chat starts with them (switches in POST /api/chats);
  • attach images, audio and other files with the buttons, or paste an image. They go with the first message;
  • dictate, use the shortcuts row above the box, and type / for the Home actions;
  • Enter sends and Shift+Enter adds a line.

  The text you type on Home stays in the browser across a reload until you send it (staged files stay only until the page closes). Send creates the chat, sends the message with its files and opens the chat at /app/chats/<id>. If the message cannot be sent, the new chat is removed and the text and files stay on Home. Home also lists your newest chats under Jump back in.

• The sidebar lists your most recent chats under the main entries, with New chat (the + beside Recent chats, which opens Home) and All chats. When the sidebar is collapsed, only the All chats icon shows. There is no separate Chats entry: Home is where a chat starts.

• All chats (/app/chats/all) is your chat history: open it from the sidebar or from All chats next to Jump back in on Home. Type to find a chat by its name or by what was said in it (the server search); the line under a match shows where it matched. Open, rename (F2), copy, export as Markdown or delete one, clear them all, or import a JSON export. A deleted chat can be brought back for a few seconds with Undo; then the server deletes it.

  The page lists the chats you started. Chats that something else started (a connector, a trigger, an agent job or a page) have a second tab, From add-ons and automations, which appears once there is one. It groups them by what started them: first the kind (triggers, connectors, jobs, pages, any other), then the origin itself, such as one connector binding or one trigger, with the origin’s name, how many chats it has, when it was last active, a Running mark while a turn runs and Waiting for you when a chat needs you (its turn paused at the step limit, or an unread inbox item asks for you). A link opens the origin’s page. These chats do not appear in the sidebar, in Jump back in or in the My chats tab; the All chats entry in the sidebar shows a number when some of them wait for you. Ctrl+K in a transcript still lists and finds every chat, with a badge on the ones you did not start. Opening one shows “This conversation was started by …” over the transcript, with a link to the origin. The browser remembers which tab you used last.

• Old addresses. /app/chats with no chat id opens Home. A ?model= in the address selects that model on Home, so /app/chats?model=<id> and the older /app/chat/<model> still start a chat on that model.

The chat page

The chat page (/app/chats/<id>) shows one chat.

• Conversations. Ctrl+K (Cmd+K on a Mac), or Chats in the header, opens the same list as All chats over the chat, to move to another chat without leaving the page.
• A new chat. New chat in the More menu, in the Ctrl+K list and /new in the message box open Home. A chat with a saved agent starts from the agent’s row on the Agents page: the chat page opens empty with the agent chosen, and its Tools and Skills menus are a draft for the new chat, as on Home. Picking another model in an open chat moves the chat to it from the next turn (not while a turn runs). /assistant starts a chat with the LocalAI management tools (administrators, when the assistant is on).
• Chat settings (the sliders icon in the header) holds the settings above: a system prompt, temperature, top P, top K, context size and reasoning effort. Save settings sends them all; they apply from the next turn.
• While the model works you can keep typing and attach files. A message you send waits over the message box and reaches the model at its next step; edit or cancel it until then. Esc or Stop ends the turn; waiting messages stay for Send now. Up in an empty box edits the last waiting message, or puts your last message back in the box.
• Drafts stay with their chat. What you type or attach in a chat stays there when you open another chat, and comes back when you return; a new chat starts empty. The browser keeps the text of each draft (not the files) across a reload, and drops it when you send it or delete the chat. A waiting message always goes to the chat you wrote it in, also when you open another chat before the server answers.
• On a message: Edit (your message) replaces it and runs the chat again from it, Regenerate (the last answer) answers again, and Branch copies the chat up to that message into a new chat. The keys are E, R and B on a focused message.
• More exports the chat as Markdown or JSON and imports a JSON export as a new chat. Chats that the old chat page kept in this browser are offered for import once (POST /api/chats/import/browser); the browser’s copy is removed when none failed.
• Under the message box the foot shows the context meter and the speed of the last model request (from the usage events). It turns amber above 80 percent of the window and red above 90.
• Tools, Skills and Sub-agents menus over the message box switch tools and skills for this chat (see above; a skill is switched by its id, and the Skills menu has Select all, Disable all and a search), and list the sub-agents of the chat with their transcript and a Stop for a running one. The Tools menu says whether the Sandbox add-on runs commands isolated, directly on this machine, or not at all. When the chat cannot run commands, the Tools menu opens with a notice, “Commands can’t run here”, and the reason: no add-on that runs code is installed, the Sandbox is off for this chat, or it cannot run on this server. An administrator gets a link to install the Sandbox or to its add-on page; anyone else is told to ask an administrator. A chip with the same words sits next to the Tools menu (on a phone, only its icon) and opens the notice. Hide removes the chip and leaves one line in the Tools menu; this browser remembers it until the reason changes. The Tools menu shows for this notice even when there is nothing to switch. Changes an add-on tool made show under the tool line with Undo when the add-on can undo them; a call the add-on refused (not_permitted, resource_unreachable, not_running, invalid_request) says why. MCP Apps show live under their tool call.
• The preview pane on the right shows what the assistant made. It opens by itself when a turn creates or changes a file, or when an answer holds a result: a whole HTML page, an SVG, a code block of 25 lines or more, or a block the answer presents as a file. A short snippet never opens it. It opens beside the thread from 1280 px and over it below that; on a phone it never opens by itself. It does not take the focus from the message box, and a screen reader hears “Preview opened: budget.xlsx”. Close it and it stays closed in that chat (this browser remembers it) until you open it again.
• Chips under an answer name the files its turn made: “Created budget.xlsx · Open preview” or “Changed …”. A chip opens the pane on its file. Files over the message box opens and closes the pane.
• What the pane shows. The selected file or code block on top, with Download, Copy (text and code) and Open in Files, then the chat’s files in two groups, Created and changed and You gave it, each with its size and turn. Spreadsheets, CSV and TSV files show as a table with a tab per sheet and the first 200 rows; Word documents and presentations as their text (the formatting is not shown); PDF files in the browser’s viewer; HTML files run in the sandbox of Pages with no network and no bridge; images, Markdown, JSON, code, audio and video with their own views; any other type as a card with Download. An add-on that previews a type (the files.preview slot) replaces the built-in view for it. Drop files on the pane to attach them to your next message. A file the model received as an image or video is marked In context.
• Code blocks in an answer have Copy and Download, and a block that is a result has Open preview.
• A trigger the model proposes shows as a card under its tool line with Create trigger, Edit (name and schedule or folder) and Dismiss.
• A change of a trigger the model asks for shows as a card under its tool line: an edit lists each field before and after with Apply and Dismiss, a delete shows the trigger with Delete and Keep, and a pause or a resume, which applies at once, is a receipt with Undo. See Changes from a chat.
• Shortcuts over the message box are the prompts of your LocalAI/shortcuts.json, or the default starters without it. A click puts one in the box; Edit shortcuts changes the list. See Make LocalAI yours.
• Find (Ctrl+Shift+F), focus mode, copying the chat as Markdown and the keyboard shortcuts work as before.

Administrators find every user’s agents, triggers and connectors under Operate > Settings > Chats of all users. The agent tasks and jobs have a page of their own, Agents > Tasks (/app/agent-tasks).

Troubleshooting a failed reply

When a turn fails, the thread shows one banner: “The reply failed”, the reason in plain words, what to do about it, a Retry button and, under Technical detail, the error text with addresses, paths and keys removed. The full cause is in the server log. The banner names the cause when LocalAI can tell:

The banner stands after the messages, tool calls and results that the turn produced before it failed: nothing of them is removed. Retry goes on from where the turn stopped (POST /api/chats/{id}/resume). The model keeps its own state, so a tool call that already has a result is not made again, a step that did not finish is done again, the messages you sent while the turn ran stay, and a summary made by a compaction stays as it is. A turn that a restart of the server interrupted can be resumed the same way. With --chats-auto-resume the server does it, and the card says that the server is going on by itself while it waits. The chat shows such a turn as The reply was interrupted, keeps everything written so far, and resumes it by itself after a short wait: up to 3 tries, with a wait that doubles from 3 seconds up to 30 seconds. Stop trying cancels the wait, and Retry resumes at once and starts the count again. Only an interrupted turn is resumed this way; a turn that failed (a model error, a refused key) waits for you, and so does an interruption older than 10 minutes. When the connection to the server is lost for more than two seconds, the chat says “Connection lost. Reconnecting.” until it is back. A second click, or a click in another window, starts nothing. To answer your last message again from the start, use Regenerate on the message.

The reason is stored with the chat, so a reload shows the same banner as the live page, for a day after the turn. A new turn clears the banner.

Moving from the old chat

The old chat page, the agents, the agent jobs and the old skills were replaced by the chats. At the first start the server converts what they left; see Moving from the old chat and agents.

API reference

The routes are listed under the chats tag at /swagger/index.html, and GET /api/instructions/chats returns a machine-readable summary.

Shared filesystem for Files

Files selects its blob backend automatically, with no separate workspace path or coordination flag:

This applies to standalone servers, frontends, optional chat workers and the add-on owner. An owner honors configured S3 without joining the distributed control plane or changing its role. Global model/input staging is unchanged. Standalone JSON/SQLite filesystem behavior and existing blob paths remain stable. Without a data path and without S3, Files is disabled; temporary scratch never becomes authoritative filesystem storage. With S3 and a database, local cache may be temporary and is removed at shutdown. JSON metadata still needs a data path. Configured S3 errors and PostgreSQL workspace initialization errors fail startup rather than selecting another backend.

Distributed Files requires shared PostgreSQL metadata. PostgreSQL owns names, authorization, revisions and blob references; immutable content-addressed bytes live in the selected backend. Per-instance caches and scratch are disposable. For filesystem storage, every Files consumer must mount the same existing data directory/backing storage and use the same PostgreSQL database: frontends, the add-on owner and optional chat workers. Inference-only nodes need no Files mount. Equal path strings do not prove shared volume identity. With PostgreSQL, the first node to start writes a random .volume-id file in DataPath/chats/blobs and records the same id in the database; every node compares the two at startup and refuses to start on a mismatch or when the file is missing. This catches a volume that is not shared. It does not prove that the storage is coherent. Other data-path contents do not thereby become cluster-safe.

Keep the canonical backing directory service-controlled, with compatible UID/GID and permissions for every participant. LocalAI does not recursively chmod/chown existing trees. Ordinary platform path aliases are resolved, while symlinks inside the canonical blob tree are rejected; do not allow untrusted writers to replace paths or redirect mounts. A same-node RWO/local-path volume needs enforced co-placement and provides no cross-node failover guarantee. Multi-node use needs coherent shared storage, normally an appropriate RWX volume: verify exclusive creation, atomic same-filesystem rename, immediate cross-client visibility, file sync and directory sync durability. An RWX label alone does not guarantee these semantics; validate crash/power-loss behavior with the storage provider.

All PostgreSQL-backed direct-filesystem workspaces automatically hold the revision lock through blob ingest and metadata publication, including non-distributed owners. This serializes metadata writes during slow uploads. Blocked operations must honor request context cancellation. Orphan cleanup uses a bounded 30-second context; cancellation can defer cleanup to a later pass. S3 is an alternative to this shared-filesystem deployment contract; its local cache is not treated as a shared filesystem.

Saved agents, triggers and inbox

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:

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 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.

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), the tool switches builtins_off and builtins_on and the connections, which it keeps when the body does not name them (an empty list or object clears them). Chats that already run with the agent use the new definition from their next turn. Another user’s agent is 404, unless it is shared with you: then you may read it and chat with it, and an edit, a delete or an export is 403.

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.

Memory of an agent

The optional field memory chooses the notes of an agent: mine_and_own (reads your notes and its own, saves to its own; the interface sets it for a new agent), own, mine or none. The form shows the level from this field and the grant memory.write: none is Off, any other choice without the grant is Reads notes, and any other choice with the grant is Reads and saves notes. Nothing else is stored. An agent without it is “as before”: it reads notes when its add-ons name memory, and the model chooses where a note goes. The host enforces the choice. A PUT without memory keeps the stored one. DELETE /api/chats/agents/{id}?memory=keep|export|delete says what to do with the agent’s own notes (default keep). The optional field memory_save (always, auto or never) is the agent’s own rule for saving a note: always and never can only be stricter than the person’s setting, auto (Save it and tell me) lets this agent save at once even when the person’s level is ask (the person’s own always and never still hold), ask is refused with a 400, a PUT without it keeps the stored rule, and use_mine clears it. See Short memory.

What it can use

The agent form has one section, What it can use, with three sources and the tool levels on top:

• Built-in tools: the groups LocalAI serves itself, with their options.
• Add-ons: one row for each add-on, with its switch, the account it uses, a Right now sentence, the skills that come with it and its tools (the ones that change data are marked).
• MCP servers: a picker over your defined MCP connectors and the MCP servers of the agent’s model, one switch each, with a search field when there are many. They write the same mcp_servers list as before; they no longer sit under Advanced, and there is no free text.

A level (Look only, Assistant, Full) sets the built-in tools and permissions only. It does not touch add-ons, accounts, MCP servers or skills.

Right now says what a chat of the agent gets from the add-on, by the same rule the server uses to pick the account: an add-on that is off offers nothing; one that needs no account just works; the accounts the agent names are used; with none named, your only account is used; with two or more and none named, a chat asks you to pick one before it gets any tool and a run with nobody there (a trigger, a messaging chat) gets none. That last case, and an add-on with no account at all, are shown in amber and in the Effective view as blocked.

Ticking an account switches the add-on on, as it does in a chat. Switching the add-on off keeps the accounts, shown as Kept for later. Switching an add-on on turns on the skills that come with it, with the same Undo and Keep notice as a level; switching it off turns off only those skills. Nothing new is stored for this: the skills that come with an add-on are read from the skill list. Skills of an add-on show in the Skills list as “from” the add-on’s title. The skills that the memory provider ships are granted by the host with the notes; the Memory section shows them once, without switches.

Connections of an agent

An add-on whose tools run with the token of one of your connections lets the agent name which accounts its chats may use. In the agent form, the add-on’s row in What it can use has an Account it uses list with a checkbox for each connection. A chat of the agent uses that set, shows it read only, and cannot change it. With two or more in the set, the model names the connection in each tool call (see The connections of an add-on). With none ticked each chat chooses its own (with one connection, it is used); until a person chooses, the add-on’s tools are not offered. Many agents can use the same connection; the connection’s row on its add-on page says how many do. The messaging connections that answer with the agent are listed under Identity, read only.

Over the API an agent has connections, an object from add-on ID to a list of binding IDs ({"<add-on id>": ["<binding id>", ...]}). Every binding must be yours and belong to that add-on, else 400. A single binding ID in place of the list is read as a set of one. A PUT that does not name connections keeps them, and {} clears them. The export file never carries them: a binding ID belongs to one server, so the format and its version are unchanged, and an imported agent has no connections until you choose some.

Resources of an agent

Some add-ons keep their data in resources that you own or were granted, such as the databases of Tables. An add-on can ask that each saved agent names the resources it may use. In the agent form, the add-on’s row in What it can use then lists your resources under the add-on’s own word for them (“Which databases it may use”), each with a checkbox and a mode: Read or Read and change. Nothing ticked means the agent can use none, and the row says so. The words come from the add-on’s manifest (noun, noun_plural and their translation); the form names no add-on.

Over the API an agent has resources, an object from add-on ID to a list of {"id": "<resource id>", "mode": "read" | "write"}. A PUT that does not name resources keeps the stored list, and {} clears it. A mode other than read or write, a repeated resource or an ID that is not a resource ID is a 400. The field has no effect on an add-on that does not opt in. GET /api/chats/agents/addons/{addon}/resources lists what you can give an agent for one add-on (items with id, name and your own role, and the noun and noun_plural the add-on uses; lang or Accept-Language picks a translation the add-on has). The add-on rows of GET /api/chats/draft/tools and GET /api/chats/{id}/tools also carry tool_list (the tools of the add-on, each read or write) and resources (the words, set only for an add-on that opts in).

The host applies the list on every tool call that takes a resource, as one more link after what you may use yourself (you own it, or it was shared with you):

• a call on a resource that is not on the list is refused, and the add-on is not called (code resource_not_in_agent_list);
• a call that changes a resource listed as read is refused (resource_read_only_for_agent);
• a tool that names no resource, such as one that creates a new one, is not affected;
• the list tool of the add-on shows the agent only the resources on the list, and a read resource shows as viewer;
• a chat of the agent cannot select a resource outside the list (403, type resource_not_in_agent_list), and a selection made earlier is checked again at each call;
• the chats that triggers and jobs of the agent start, and the sub-agents of a chat, use the same list. A sub-agent never reaches more than the agents above it;
• the host reads the list from the stored agent at each call, so a change holds at once.

In a messaging chat the tools that change things need the tools.write permission of the connection, as for an add-on that holds a credential (see Connectors); paired people have them without the tick only for an add-on the agent is connected to. The access view and its preview say when an agent whose add-ons only change resources has none to change (agent_resources_none) or only read ones (agent_resources_read_only), and point at the agent. The export file never carries resources: a resource ID belongs to one server. An import drops the field and says so under warnings.

An add-on opts in with capabilities.resources.agentScoped in its manifest (feature level 2; see the manifest).

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.

• 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 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 is one choice in three words:

• No files: the agent cannot list, read, write or search any of your files, with any tool. It is the Files tool switch (builtins_off holds files). The server then fences the agent’s chats to their own chat folder and the read-only skill layers, so the image and audio helpers, a Sandbox command and an add-on cannot reach your files either. Files you attach to a chat stay in that chat. Any folder stored on the agent is ignored while Files is off, and choosing No files in the form removes the folders from the agent. The Look only and Assistant levels already mean No files and now select it. Watching a folder needs file access: a trigger that watches a folder still starts for such an agent but cannot open the files that arrive, and the trigger editor says so.
• All my files: the Files tool is on and the agent has no folder. A new agent starts here, and an agent saved before this choice with Files on and no folder reads the same.
• Only these folders: the Files tool is on and the agent has a folder list.

The folder rows, the picker and the access of each row show only for Only these folders. The choice shows in the agent’s header and page, in the Effective view (Cannot reach any of your files, Can reach all your files or Can reach only N folders) and in the Try it list of what a test chat does not use. The API has no new field: send builtins_off with or without files and folders.

For Only these 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, knowledge.write, triggers.propose, triggers.run, talkback.channels, talkback.new_channel, files.upload, act.files, act.addons, act.send, act.spend, saved_agents (the opt-in group of that name; granting it also switches the group on) and history.read (the agent can search and read your earlier chats with the opt-in group Past chats; granting it also switches the group on, an agent that works in a folder reads only its own chats, and a run that nobody watches, a messaging chat and a sub-agent never hold it; see Past chats). 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. knowledge.write (Add to knowledge, sensitive) lets it propose a text for one of its collections; see Adding to Knowledge. The Tools list of the agent form and of a chat show each grant once, as an option under the switch it refines: “Create and manage triggers” holds “Also propose from messaging apps” (triggers.propose) and “Let triggers start from messaging apps” (triggers.run); “Suggested changes” holds the five *.write grants; “Knowledge” holds knowledge.write; “Your files” holds files.upload and act.files. An option is greyed, with the reason, while its switch is off, and keeps its stored value. talkback.channels and talkback.new_channel are in the section “Messaging apps”, and act.addons, act.send and act.spend in “When nobody is watching”. “Saved agents” is one switch: either the group saved_agents in builtins_on or the grant of that name turns it on, switching it off removes both, and switching it on adds only the group. Each switch and option has one line that says what it lets the model do, and the form names a messaging connection of the agent that does not allow an option the agent holds, with a link to the permissions of that connection. A chat of the agent lists the grants it holds, read only. “Select all” never touches a grant. 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 (a sender’s files going to the agent; it does not let the agent send files out), 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 the ceiling of the action policy of unattended runs (see Action policy of unattended runs).

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, memory and memory_save are extra fields of any version; a server that does not know them ignores them, so the agent arrives without the grants, as before and without its own save rule (it then follows the setting of the person); a server that knows memory_save but only always and never refuses a file with auto (400). An import makes a new agent: it has the exported memory choice and memory_save rule and none of the original’s notes. 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}. For an agent shared with you, the runs are your own chats with it.

Share an agent

You can share a saved agent with other people on the server, or with everyone. Use Share in the row menu of the agent or in the header of its page. The Share dialog finds people by name and gives each one a role:

Only you edit, delete, export or share the agent. The person can not make a trigger, a task or a connector with it, and your own triggers and connectors keep running as you.

A person who chats with a shared agent runs it as themselves. The chat, the memory, the files, the folders, the add-ons, the collections and the connections are theirs, exactly as for their own agent. Only the definition comes from you. Your files are never used for them, and no answer to them carries a token, a secret or the ID of your connection.

The agent never runs with more than the person’s own chats start with. With the role use the person does not read your instructions, so what the agent asks for is narrowed to what their own new chat gets:

• Network. Their chat starts with the narrower of the agent’s network preset and the instance default for a new chat, never with your preset above it. The person can widen the network of the chat themselves, up to the instance limit.
• Opt-in tool groups. The groups the agent turns on (its saved agents, the earlier chats) start off in their chat. The person can turn them on in the chat.
• Built-in grants. The agent holds a grant only when the person may use it, as for their own agent.

The connections the agent names are yours. A chat of the person uses one of them only while you share that connection with them (role use), and only when it is not a choice:

• When the person has no connection of their own for the add-on and holds a grant on exactly one of the agent’s connections for it, the chat uses that one.
• When the person has a connection of their own for the add-on, or holds grants on several of the agent’s connections for it, the chat uses none of yours by itself. The person picks the connection in the chat, from their own and the ones shared with them.
• The agent’s connections do not lock the person’s chat, as they do in your own chats: the person may always choose another one.

Sharing the agent does not share what it uses. Before the dialog adds a person, it lists what the agent names and asks you, for each thing that can be shared, to choose one of the options the server offers for it, or Not shared. The options come from the roles the kind of the thing grants:

A folder, a skill, an add-on, an MCP server and a built-in grant can not be shared this way: the person needs access of their own. The dialog applies each choice as a grant on that thing, for the same person.

The agent page of a person tells them what they are missing: each thing the agent names is ok, missing (not shared with them) or unavailable (the server or their account does not offer it). A connection of yours is ok while you share it with them and missing otherwise. The list also shows the network preset and the opt-in tool groups the agent asks for: ask when their chat starts without it and they can turn it on, unavailable when the instance does not allow it. A chat with the agent shows the same notice before the first message.

When you lower the role or remove the person, a run of the agent in one of their chats stops, and the chat takes no new message with the agent. Their past chats stay readable. When you delete the agent, every grant on it is removed.

The API:

Share with the sharing API, kind agent, the ID from POST .../share, roles use and viewer:

curl -X PUT -b session=... \
  -H 'Content-Type: application/json' \
  -H 'X-LocalAI-Confirm: r0123456789abcdef0123456789abcde' \
  -H 'Sec-Fetch-Site: same-origin' -H 'Sec-Fetch-Mode: cors' -H 'Sec-Fetch-Dest: empty' \
  -d '{"role":"use"}' \
  http://localhost:8080/api/shares/agent/r0123456789abcdef0123456789abcde/grants/@everyone

Errors: 403 with authorization_error for an action that is the owner’s alone; 404 for an agent that does not exist or is not shared with you (the two are one answer); 409 with agent_not_shared for a new message in a chat whose agent is no longer shared with you; 409 with sharing_disabled when the server does not share agents.

Sharing needs named accounts. In local-owner mode, with no accounts, the agents show no sharing. The grants live in the sharing policy of the add-on owner (see Share with your team). The agent keeps only the ID of its sharing record, in the agents table, so every frontend reads the same one. A frontend that is not the add-on owner asks the owner for every sharing decision, so a shared agent works on every frontend, also when the add-on owner is a separate process (--addons-role=owner). When the owner cannot be reached, no shared agent is listed or run: the agents list shows your own only, a new message in a chat with a shared agent is refused, and a running turn of a shared agent stops. With add-ons off, no agent is shared.

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 instead (see Loop or trigger? there). There are two kinds.

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 by default (chats_trigger_run_limit, 1m to 24h). A trigger can set a shorter or longer time limit of its own with run_limit, a duration such as 30m or 2h from 1m to 24h; empty or 0 means the administrator’s limit. That setting is the ceiling: a trigger whose run_limit is longer is saved as written but each run is stopped at the ceiling, and a lowered ceiling applies to the next run and to the check of a run that is found running after a restart. The API shows run_limit and effective_run_limit, the one that applies now. A proposal from a messaging app is held to the same ceiling when the trigger is set up by itself. At most 2 runs go at once, one per trigger, and a trigger has a daily limit (daily_cap, at most 1000 or chats_trigger_max_daily_cap when an administrator sets it lower). When you set none, a schedule trigger gets one run for each time its schedule fires in a day, and at least 24: a trigger every 30 minutes gets 48 and one every 5 minutes gets 288. A limit you set is used as written. A schedule trigger is switched off, and you get a notification, after 3 failed runs in a row. One that runs more often than hourly is also switched off after 3 runs in a row that the daily limit skipped. A run that is skipped because the previous run is still going is recorded once for a stretch of such skips, not once for each missed time. A run that is skipped or fails shows its reason on the trigger. An administrator sets the limits of the triggers in the runtime settings.
• 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.

Action policy of unattended runs

A trigger run or an agent job has nobody at the screen to approve a step, so it starts read only. LocalAI checks every tool call of such a run at the moment of the call, not in the prompt. A tool that only reads always runs. Any other tool runs only if the run holds the grant for its class. Add-on tools and MCP tools always have a class. The other built-in tools either read or need a grant that a run which started by itself never holds. Nothing is allowed on a doubt: a trigger or a connection that cannot be read at that moment gives a read only run.

What a run holds:

• A trigger run holds the acts of its trigger, limited to the act.* grants of its agent (builtins). A trigger without an agent has no ceiling but its own acts. Set acts in the body of POST /api/chats/triggers or PUT /api/chats/triggers/{id}: leave it out to keep the value, send [] to clear it. The trigger form (the Permissions section on the Triggers page) edits the same list. A model can ask for acts only when it proposes a trigger (propose_trigger takes an optional acts list), and only for what its own agent holds; no tool changes the acts of a trigger afterwards. The proposal card lists them, and confirming it grants exactly those. A proposal from a chat of a messaging app carries only the acts that the binding allows (approval.acts, see Runs may act) and the agent holds; the rest is dropped and named in the proposal. A connection starts such a trigger without asking only in the auto mode, when every act is allowed for the binding and the sender is paired; otherwise it is left for a yes. A trigger whose plan names a file it writes (plan.writes) also holds act.files, because you saw that file on the proposal card. Triggers that exist before this change keep running, but they now read only unless they set acts or plan.writes.
• An agent job run holds the act.* grants of its agent, and nothing without an agent. A job has no acts of its own.
• Read only runs. A trigger whose proposal said its runs only read (access: read_only), or that a connection made without asking while its approval mode is auto_readonly (see Approval modes), holds nothing: every tool that is not a read is refused, whatever acts and the agent say. A connection that cannot be read is treated as auto_readonly.
• Sub-agents. A sub-agent of an unattended run has the same limits as its parent. A run that nobody watches cannot start a saved agent as a sub-agent.

The trigger as REST returns it says what applies: acts is the list the trigger holds, acts_held the part of it that applies to a run (within the grants of the agent, plus act.files for a plan that writes a file), read_only whether a run can only read and read_only_why why: no_acts (it holds none), agent (its agent holds none of them), declared (the proposal said read_only) or binding (a connection in auto_readonly mode made it). A trigger that a connection made without asking also holds only the acts that its binding allows now, and binding gives the ID of that connection (it is left out for other triggers). The Triggers page shows the same: a “Read only” mark on each row, and the reason on the trigger.

A refused tool stays in the tool list and answers with one plain sentence instead of running, for example “I did not run write_file: nobody is here to approve it and this run has no permission for act.files. Say in your answer what you wanted to do; the owner can allow act.files for this run.” The model then reports it in its answer. The refusal is a result, not an error, so the model does not retry. Each call of a tool that is not a read writes one log line, studio: unattended action, with the chat, the trigger or job, the tool, allowed, reason (granted, not_granted or read_only) and the missing grant.

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.

What the model is told, and what is recorded

• Timers. In Studio, when takes a schedule text, {"file_arrives_in": folder} and the timers {"in": "2 hours"}, {"at": "18:00"} and {"at": "2026-11-15 09:00"}, which set a one-off trigger. A time of day is the next time it is that time; a date and a time names the day, and one that is past or less than a minute away is refused. The zone is time_zone (also read inside when, next to at), or the timezone in user.json; without either, at is an error that says to pass one. The description of propose_trigger and update_trigger gives today’s date and your zone, so the model does not work out a day, and it changes once a day.
• Proof in the result. The result of propose_trigger, update_trigger and delete_trigger ends with the state that was read back from the store after the write: ref, state (proposed, active, paused, deleted_pending, withdrawn), active, now, next_run (RFC 3339, from the schedule and the zone), when a proposal lapses (expires) and change: "pending" while an update or a delete waits. The same proposal made again says that it is the one that already waits.
• A turn without trigger tools. When none of the four tools is offered in a turn (the server runs no triggers, the chat switched the group off, a run nobody watches, a sub-agent, a messaging chat without an agent or without the permission, or an account without the feature), the note of the turn starts with one line that names the reason and says not to claim a reminder or a schedule was set. A turn that has the tools gets no such line.
• Trace. Each turn logs one info line, studio: trigger tools of the turn, with the chat, the origin, the agent, the tools offered, the reason for each one refused, whether the sender held triggers.propose and triggers.change, and the approval mode of a connection. Each call of a trigger tool logs studio: trigger tool call with the tool, ok, the error text and the ref. A change from a messaging chat also logs studio: trigger change from a messaging chat with the mode used. No line holds the arguments or any message text.

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 (chats_trigger_max_per_user).

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 trigger runs at most once every 5 minutes, however it is made. A shorter one (for example * * * * *, every minute) is refused with the reason, and the model is told to propose a slower one. An edit of the proposal keeps the same floor, and so do the Triggers page and the REST API when you create a trigger or change its schedule. A trigger that was saved with a shorter schedule before this floor keeps running; you can rename it or edit its prompt, and only a change of its schedule is checked.

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). A proposal can also ask for a time limit for each run (run_limit, for example 30m). 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), the time limit when there is one (and the lower limit that applies if the administrator set one) 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, run_limit, 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 every 5 minutes, 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.

list_triggers also lists the proposals that still wait, with state: "proposed" (the other states are active and paused), and include_prompt works on one. A delete_trigger with the ref of a proposal that waits withdraws it at once; update_trigger on such a ref is an error that says to withdraw it and propose it again.

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.

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. A chat that a messaging app started gets propose_trigger and list_triggers when the connection holds triggers.propose and the agent holds the grant “Also propose from messaging apps”. It gets update_trigger and delete_trigger only when the connection holds triggers.change (off by default, sensitive: only a paired sender can use it) and the sender of the message holds it; the approval mode of the connection then decides whether the owner confirms each change in the chat or it applies at once (see Triggers from a connector chat).

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.

The Notifications entry is in the app on every page, not only in the chat page. On a wide screen it sits in the sidebar, above Administration; on a narrow screen it is an icon of the rail; on a phone it is a bell in the header (and an entry in the menu). It shows the unread count (99+ above 99), in red when an unread item is a failure, and opens one panel (a sheet over the bottom of the screen on a phone). An administrator always sees the entry. Anyone else sees it once they have items. Nobody sees it when the chats are off or the account lacks the chats feature. A change that waits for you is listed in the panel but is not in the count. An administrator also sees an Activity tab in the panel, with installs, updates and removals (see Activity); operations are never in the count. In the panel:

• 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. The exception is a set item (see below), which no trim removes.

Items that LocalAI keeps up to date

Most items are written once. LocalAI itself writes a few kinds that it keeps up to date, such as the list of updates that are available. An item like that has a key, and you have at most one for each key.

• A set item shows a set of things, each with an id. When the set gets an id it did not show before, the item comes back as a new, unread item at the top. It reaches the browser push and the Telegram chat once, like any new item. When the set only gets smaller, or its text changes, the item is edited in place: it keeps its place, its read state and its hidden state, and nothing is pushed. An empty set removes the item.
• Delete, Clear read and Clear all do not forget a keyed item: they hide it. It stays hidden while the set is the same or smaller, and it comes back, unread, only for a new id. Marking it read keeps it in the list, and later edits do not make it unread again.
• A once item is posted when its key is new and never again, also after you deleted it. LocalAI uses one for each result of an automatic update, so a failure that repeats at the next pass does not fill the inbox.

Some items have a code and params in the API (updates.digest, updates.result, updates.checkFailed). The app words them in your language from the params. title and body stay in English: they are the fallback for a client that does not know the code, and the text of browser push and Telegram. The update items are described in Updates in the inbox.

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. The frontend that stores a new or revived item runs the push and the Telegram forward, so each happens once in a cluster. An item that LocalAI writes on its own (see above) is written by one frontend only: the one that holds the lock of the work that produces it.

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:

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.

Agent tasks and jobs

A task is a saved prompt template. A job is one run of a task: a chat that runs in the background, as the owner of the task, with the same loop as every other chat. Use them to call LocalAI from a script, a CI pipeline or another service: start a job with parameters, poll it, and read the answer, or have LocalAI call a webhook when it ends.

The API keeps the paths and the JSON it had before the chats. A job is an ordinary chat with origin job, so you can open it from All chats and read its transcript.

The Tasks page

Agents > Tasks (/app/agent-tasks) lists your tasks with who runs them, the values their prompt asks for, and how the last run went. Search the list, or show only the tasks that are on or off. Each row has an On switch, Run and a menu with Open, Edit and Delete.

• New task opens a side sheet: a name, a description, a model or one of your saved agents, the prompt, and on or off. The sheet lists the parameters the prompt names as you type, and says which required field is missing when you save.
• Run starts a task at once when its prompt names no parameter. Otherwise a sheet asks for each value and shows the prompt as the task receives it.
• Open shows the task in a pane with three tabs: Overview (the prompt, the values it asks for and a curl call that runs it by name), Runs (its jobs) and Settings (on or off, its webhooks, delete).
• Run history lists every job by day. Filter it by state (in progress, done, failed, cancelled) and by task. Open a job to see the values it ran with, its answer or error (with Copy), its steps, the webhook outcome and a link to the chat that holds it. Cancel stops a job in progress; Run again and Delete run act on a finished one.

Webhooks are set over the API; the page keeps a task’s webhooks as they are. An administrator can switch on All users to see the tasks and jobs of every user, read-only.

A task

curl -X POST .../api/agent/tasks -d '{
  "name": "weekly-summary",
  "model": "my-model",
  "prompt": "Summarise {{.topic}} in five lines.",
  "webhooks": [{"url": "https://ci.example.com/hook", "headers": {"Authorization": "Bearer ..."}}]
}'

GET, PUT and DELETE /api/agent/tasks/{id} read, replace and delete one; GET /api/agent/tasks lists yours. Deleting a task keeps its jobs until their retention passes.

cron, cron_parameters and multimedia_sources are refused. A task does not schedule itself: put the saved agent on a trigger.

A job

curl -X POST .../api/agent/jobs/execute -d '{"task_id": "<id>", "parameters": {"topic": "the week"}}'
curl -X POST .../api/agent/tasks/weekly-summary/execute -d '{"topic": "the week"}'
curl .../api/agent/jobs/<job_id>

Both calls answer 201 with job_id, status and the url to poll. The job runs in the background.

GET /api/agent/jobs lists your jobs, newest first, and takes task_id, status and limit. POST /api/agent/jobs/{id}/cancel stops a running job (409 when it has ended). POST .../{id}/rerun starts a new job with the same task and parameters. DELETE .../{id} stops the job if it runs and deletes it with its chat.

Attachments. images, videos, audios and files take base64 data URIs (data:<type>;base64,<data>), at most 8 of up to 20 MB each. They are saved in your files for the job to read, so the files must be on (a data path is set). An address is never fetched: the server makes no request for a caller, and 400 names the field. They are not kept for a rerun.

Limits. A user can have 10 jobs running at once (429) and 200 tasks. A job that runs longer than LOCALAI_MCP_CI_JOB_TIMEOUT (default 10m) is stopped and ends as cancelled with the reason. Ended jobs and their chats are removed after LOCALAI_AGENT_JOB_RETENTION_DAYS (default 30).

Webhooks

When a job ends the server calls each webhook of the task: url, method (POST, PUT or PATCH; default POST), headers and an optional payload_template. Without a template the body is JSON with job_id, task_id, task_name, status, result, error, parameters, started_at and completed_at. A template is a Go template with sprig functions and json (not env, expandenv and getHostByName) over .Job, .Task, .Result, .Error, .Parameters and .Status.

A failed call is retried three times, after 1, 2 and 4 seconds. The job keeps webhook_sent and, when something failed, webhook_error. The status of the job does not change.

The address must be http or https, with no credentials in it. An address on a private or internal network (localhost, 10.x, 192.168.x, .local) is refused, when the task is saved and again when the call is made, unless an administrator allows it with the mcp_connectors_allow_private setting. Header values may hold a credential, so the API never returns them: a header comes back as [hidden], and sending [hidden] back in an update keeps the stored value. The headers are stored as they are in the task store, which is protected like the rest of the chats data. Do not put a secret you cannot rotate in a header.

Who can see them

Tasks and jobs belong to their owner; another user’s id is 404. An administrator can read any job (GET /api/agent/jobs/{id}) and list every user’s tasks and jobs with ?all_users=true, which adds a user_groups object keyed by owner. The view is read-only. To switch off or delete what a user set up, see the administrator’s view of agents, triggers and connectors under /api/chats/admin.

Clusters

Tasks and job records are in the database, shared by every frontend. A job is watched by the frontend that received the request. Its turn runs there too, unless the frontends send unattended turns to chat workers: then a chat worker runs it, and the frontend still watches it and stops it at the run limit. If the process that runs the turn dies, the chat is ended by the usual reaper, and the leader’s sweep (an advisory lock) records the end and delivers the webhooks of a job whose frontend is gone. The same sweep removes jobs past their retention.

Short memory

Memory is built into LocalAI. It gives your chats a few notes about you. The model reads the note that matches a request before it answers, and by default it saves a new note only after you confirm it. You can change that in your account settings. Nothing needs to be installed.

It is for the facts that change what a good answer is: where you live, what you eat, the language and units you use, how you want answers. It is not a store for large documents. Use Knowledge to search many files.

How it works

Each turn, the host puts an index of your notes in the prompt, under a fixed header that asks the model to read the matching topic before it answers. The notes are wrapped as data you saved, never as instructions. The index is a list of lines such as - home: lives in Rome -> home.md. The model opens a topic with the context_read tool. Two built-in skills, memory and memory-check-own-files, tell the model to consult memory for almost every request and to say what it can and cannot read. The server grants these skills itself, in the same turns that read your notes. A saved agent does not list them in its Skills, and an agent saved before this existed gets them too. They are not granted when the agent’s memory choice is None, when memory is off, when the chat is private, or to a sender in a messaging app who is not paired (that sender gets none of your personal notes). When an add-on serves the notes, the skills of that add-on are granted in their place. The skill list marks them with provider: "memory" and locked: true. While you have no notes, nothing is added to the prompt.

There are three kinds of notes, each in the Memory folder of your files. The Memory tab lists them in tabs: yours, one for each saved agent, and Deleted agents.

An index has at most 40 lines and 2 KiB. All indexes of a turn together have at most 6 KiB. The details of a topic sit in a file next to the index.

Turn memory off

Memory has one switch, On or Off, at the top of the Memory tab of your account settings (Your settings, then Memory). It is on until you turn it off.

When memory is off:

• Nothing from your notes is put in the prompt, in any chat, agent, trigger or run that starts by itself.
• The model has no memory tool or skill: it cannot read a note, propose one or save one.
• The model is told in one line that memory is off. If you ask it to remember something, it says that memory is off and that you can turn it on again.
• Your notes stay where they are. You can still read, edit, export and delete them on the Memory tab while memory is off.

The narrowest level wins, and a wider level never overrides a narrower one:

1. This chat is private (see below).
2. The agent of the chat turns memory off in its Tools list.
3. Your switch in the account settings is off.
4. The server has files off, because notes are files.

A saved agent cannot widen your choice: with your switch off, an agent that is allowed to save notes still reads and saves none. The agent form shows “Memory is off in your settings” as a read-only line.

Choose the provider

Built-in memory is the default. At the top of the Memory tab, Memory provider lists the providers you can pick: Built-in, Off, and every installed add-on that says it can serve memory (see Provider slots). One serves at a time. When you pick an add-on, its index files, skills and memory tools replace the built-in ones, and the built-in provider does not read or save notes. Your existing notes stay where they are.

Off is the same as the switch above: the two are one choice.

If the add-on you picked stops, is disabled or is removed, memory is off and the tab says which add-on it was. Memory does not move to the built-in provider by itself, so a note is never saved somewhere you did not choose. Pick the add-on again once it runs, or pick Built-in. In a chat, GET /api/chats/{id}/tools reports the code memory_provider_unavailable.

Private chat

In the Tools menu of a chat, the Memory row has a switch. Turn it off to make the chat private: it neither reads nor saves memory. The server remembers it for that chat, and a chip “Private chat” and a line in the Tools menu say so. Your other chats are not affected, and notes saved earlier are not removed. It is the same switch as the group memory of PUT /api/chats/{id}/builtins; GET /api/chats/{id}/tools has a memory object ({on, code, blocked_by, fix}) that names the level that is off.

Export and forget

On the Memory tab, Export downloads your notes as a zip file (GET /api/chats/memory/export). Forget everything moves the notes to the Trash after you confirm; you can restore them from Files. Both work while memory is off.

The API

GET /api/chats/providers lists the providers of memory and PUT /api/chats/providers/memory with {provider} picks one; provider of the memory settings is what serves now.

GET /api/chats/memory reads {enabled, enabled_set, save_mode, messaging_save, save_mode_set, provider, available} and PUT /api/chats/memory with {enabled, save_mode, messaging_save} changes them (a field left out stays as it is; a value that is not allowed is a 400). The server keeps them with your other settings, so every frontend of a cluster reads the same answer. Before you choose, memory is on, unless you had disabled the old Memory add-on to stop it.

Saving and forgetting

When you ask the model to remember something, it calls propose_change. By default nothing is written at once. You confirm the proposal on the card in the chat or in the inbox, and it expires after 24 hours. A confirmed change is one change set in your files, so you can undo it. To forget a note you just saved, the model calls revert_change. For an older note it proposes a shorter file, and you confirm that too.

A file over its cap is refused, and the answer lists the current entries so the model merges them.

Choose how a note is saved

In your account settings, on the Memory tab, you choose what happens when the assistant wants to save something to your memory:

The values of save_mode are auto, ask, always and never. The choice is yours alone and the server keeps it.

Which rule applies

Several settings can have a say on one note. The strictest wins, in this order: auto is the loosest, then ask, then always, then never. One function combines them.

If your level is Always confirm or Never, nothing can loosen it: not the messaging row and not an agent that chose Save it and tell me. With Ask me first or Save it and tell me, the messaging row decides for messaging chats. When any of these cannot be read, the host asks.

These rules hold whatever you choose:

• Chats that come from a messaging app ask first, unless you chose Save it for a paired sender in a private chat (see below). The person who wrote the message is not always you, so a message from outside never saves to your memory without your confirmation. Scheduled and background runs cannot save notes at all. The bot writes the question in the chat (“I can save a note … Reply yes to save it or no to drop it”), and a sender whom you trust with the permission Confirm changes from the chat answers there with yes or no, within 24 hours. undo takes a saved note back for 30 minutes. Another sender, or one without that permission, cannot answer: the note waits in Studio for you. See Confirming a change in the chat.
• A saved agent cannot widen your choice. If you choose to be asked, it asks, even when you let it write to memory.
• A reply saves at most 5 notes at once. A long note, or one that looks like it holds a secret such as a key or a password, waits for your confirmation instead.
• An automatic note is one change set like any other. The Undo on the chat, the model’s revert_change and the Files history restore the earlier text. Every automatic note is in the audit of changes (GET /api/chats/changes/audit).

If the server cannot read your choice, it asks first.

In messaging apps

Under In messaging apps on the Memory tab you choose how a note proposed in a chat from a messaging app is saved (messaging_save):

The host decides whether a chat is one-to-one from what the platform sent for the message (a Telegram private chat, a Slack direct message, a Discord direct message). When it does not know, the chat counts as a group, so nothing is saved at once.

A note from a messaging chat goes to this conversation first (Memory/channels/...). It reaches the agent’s own notes or yours only from a paired sender, only when the agent’s memory choice allows that scope, and only after that sender confirms it: a note for another scope never saves at once. Under Always confirm only the paired sender who asked can confirm a note, in a private chat too. An agent whose memory is None saves nothing.

Reading follows the same rule. A turn from a messaging chat reads your notes and the agent’s notes only when the sender is paired with the bot. The agent’s profile (its standing rules) reaches every sender, like the agent’s instructions. A listed sender who is not paired, and anyone let in through a channel, get the notes of that conversation only. This holds for the built-in notes and for an add-on that serves the notes. If no sender is known for the turn, it counts as unpaired. The connection page shows it as the line notes.read of each kind of sender.

Memory for each agent

A saved agent has its own choice of notes. You set it in the agent form, in the Memory section, when you make the agent and again later. The host enforces it: the model does not choose where a note goes.

The section has two controls. The first says how much the agent does with notes:

No new field is stored: the form reads the level from memory and memory.write, so an agent keeps exactly what it has. Switching a level changes both fields together and offers an Undo. The second control, whose notes (the table below), shows while memory is not Off. The save level of your settings and the agent’s own save rule apply only to an agent that saves notes. The memory skills show as locked rows, on while memory is on, in the Memory section and in the Skills list. An agent that reads but cannot save still gets the skills (they also teach how to read), and the model is told that saving is off.

How it works:

• Reads. The notes in the prompt, and the scopes context_read accepts, follow the choice. The notes of a messaging conversation stay with every choice but None.
• Writes. The memory kind of propose_change accepts only the scope of the choice. The tool offered to the model lists only the scopes it may use, a note needs no scope (the host fills it in) and any other scope is refused. None offers no memory kind. The grant Remember things (memory.write) still decides whether the agent may save; the choice decides where.
• Your switch wins. With memory off in your settings, or in a private chat, every choice reads and saves nothing. An agent cannot widen your choice. The form shows “Memory is off in your settings” and the chat says which level is off.
• Sub-agents get no notes and cannot save. Triggers and other runs that start by themselves read per the choice and cannot save.
• A chat without an agent reads your notes and saves to them, as before.
• Existing agents are not changed: they show As before in the form, with a way to pick one of the clearer choices. An agent that never had the field keeps reading and saving exactly as it did. A PUT that does not send memory keeps the stored choice.
• Messaging apps. This does not change what a chat from a messaging app reads: it still reads your notes and those of its own conversation. What it saves, and where, is in In messaging apps: the conversation first, the agent’s own notes only after a paired sender confirms.
• The agent’s save rule. Under When it wants to save a note the form offers Use my setting (the default, with your current level and a link to Settings > Memory), Save it and tell me, Always confirm and Never. Always confirm and Never are only ever stricter than your level. Save it and tell me (auto) makes this one agent save each note at once and tell you in the chat, with an Undo, even when your level is Ask me first. It does not loosen your own Always confirm or Never, and every limit of an automatic save still holds: up to 5 notes a reply, a note over 4 KiB or one that looks like a secret waits for you, a sub-agent, a trigger or a job never saves by itself, and a knowledge change always asks. In a messaging chat it lifts the messaging row for this agent only for a paired sender in a one-to-one chat; notes from other senders still wait for you. The Effective view, the Notes chip and the access view of a connection (including its preview) say “Saves notes at once and tells you”. The API refuses ask with a 400. A PUT that does not send memory_save keeps the stored rule, so an older client cannot change an agent; memory_save: "use_mine" clears it.

The API fields are memory on an agent (own, mine_and_own, mine, none; absent is as before) and memory_save (always, auto, never; absent uses your setting). Both are part of an agent export file and of an import. A new agent that a client writes without memory is “as before”; the interface sends mine_and_own.

Delete or copy an agent

An agent’s own notes are the folder Memory/agents/<id>/. When you delete an agent that has notes, the interface asks what to do with them: Keep (the default), Export then delete, or Delete. DELETE /api/chats/agents/{id}?memory=keep|export|delete does the same: keep leaves them, delete moves them to the Trash, and export answers with a zip file of the notes and then moves them to the Trash. Kept notes show on the Memory tab under Deleted agents until you delete them.

Copying an agent (an export and an import) makes a new agent with the same choice and no notes: its own notes stay with the original.

Your control

The notes are plain files. Read, edit and delete them on the Memory tab of your account or on the Files page.

If you used the Memory add-on

The add-on “Short memory” is no longer needed, and it is no longer offered in the library. Its notes, its save choice and its agent setting keep working, and the server does not load its index files or skills twice. You can leave it installed or remove it; no note is lost. If you disabled the add-on to stop memory and never chose otherwise, memory stays off for you.

For add-on authors

The host serves memory itself. An add-on that wants to serve it in place of the built-in provider declares capabilities.provides with the slot memory; the person picks it in Memory provider. See Provider slots. A provider can also supply the notes of each turn, an export and a forget, and the host checks its writes against your save level; see What the host does itself with a provider. The add-on memory is an alias of the built-in provider: it stays valid and harmless. An add-on can still declare capabilities.contextFiles for its own index files; see Context files. A skill named memory or memory-check-own-files is reserved for the built-in ones.

Context compression

Context compression is an opt-in, per-model policy for chat requests that approach the model context limit. The configuration is disabled by default and does not change existing requests unless enabled is true.

name: long-context-chat
backend: llama-cpp
parameters:
  model: chat-model.gguf
compression:
  enabled: true
  trigger_at_ratio: 0.75
  keep_tail_tokens: 8000
  max_summary_tokens: 2048
  compressor_model: fast-summarizer
  on_post_compression_overflow: drop_oldest_summary

The chat middleware counts the request before inference. Requests below the configured ratio pass through unchanged. Requests above it replace the oldest complete turns with a system summary while retaining the newest messages and keeping assistant tool calls with their tool results.

Token counts use a conservative byte-level upper-bound estimate so compression never downloads a tokenizer vocabulary in the request path. Tool schemas and the configured maximum completion length are included in the context budget.

• trigger_at_ratio selects the fraction of context_size that starts compression.
• keep_tail_tokens protects the newest part of the conversation from compression.
• max_summary_tokens limits the generated summary.
• compressor_model selects a secondary model. An empty value selects the primary model.
• on_post_compression_overflow selects drop_oldest_summary or error when the compressed request still exceeds the context limit.

When omitted, trigger_at_ratio defaults to 0.75, keep_tail_tokens to 2048, max_summary_tokens to 512, and on_post_compression_overflow to error.

Compression applies to /v1/chat/completions, /chat/completions, and the LocalAI MCP chat-completion routes. Non-streaming responses include usage.compression_meta. Streaming responses include the same metadata in the trailing usage chunk when the request sets stream_options.include_usage.

Compression is not supported with cloud-proxy passthrough mode because LocalAI cannot safely rewrite an opaque provider payload. Configure cloud proxy translation mode to use context compression.

The compressor model must be installed and configured. If compressor_model is empty, LocalAI uses the primary model. A compressor failure returns an error instead of sending an over-limit request to the primary model. The drop_oldest_summary overflow policy removes up to two existing summary messages; if the request still does not fit, LocalAI returns HTTP 413.

The /metrics endpoint exports localai_compression_events_total, localai_compression_ratio, and localai_compression_duration_seconds.

LocalAI Assistant

LocalAI Assistant is an admin-only chat that manages your instance. It is a normal chat that starts with LocalAI’s own admin tools and a system prompt that teaches the model to use them safely. You can install models, manage backends, edit model configs and check system status by chatting, with no REST calls or YAML edits.

The same tools are published as a Go package and can also be served over stdio to control a remote LocalAI instance from outside (e.g. from a desktop MCP host, Cursor, or mcphost).

Start the assistant

The assistant starts from the Home page, not from the chats page. Sign in as an admin, pick a chat model with the model chip in the command bar, and use either entry:

• Type /assistant in the command bar.
• Click Manage LocalAI by chatting in the library row.

Home creates a new chat named “LocalAI Assistant” and opens it. It then appears in the chats list like any other chat, and you can come back to it later. Assistant mode is a shortcut: it switches the LocalAI admin tool group on for that chat and adds the assistant’s system prompt. The admin tools are a built-in tool group like the others (see Tool groups), so any chat of an administrator can switch them on in its Tools menu. Sub-agents never get them.

Over the API, create the chat with assistant: true:

curl -X POST http://localhost:8080/api/chats \
  -H 'Content-Type: application/json' \
  -d '{"model": "my-chat-model", "title": "LocalAI Assistant", "assistant": true}'

The server answers 403 to a user who is not an admin, 503 when the admin tools are switched off for the instance (chats_localai_admin), and 400 when the request also names a saved agent.

Once the chat is open, try:

Install Qwen 3 chat

The assistant searches the gallery, lists candidates, asks you to pick, summarises the install, and waits for your confirmation before calling install_model. While the install runs, it polls progress and reports the outcome.

Turning the assistant on and off

There is no separate switch for the assistant. The two tool groups below decide what a chat has: switch off chats_localai_admin in Settings → Tools and Home hides /assistant and the library entry, and no chat gets the admin tools. The setting applies at the next turn. An assistant chat that already exists keeps its history. The setting also covers the OpenAI-compatible metadata.localai_assistant request and the realtime assistant session: both answer 503 (“the LocalAI assistant is switched off on this server”) to an administrator while it is off, and 403 to anyone else. Creating an assistant chat in Studio is refused too. Earlier versions had a localai_assistant_enabled setting, a LOCALAI_DISABLE_ASSISTANT variable and a --disable-local-ai-assistant flag. They are deprecated and still read: when one says the assistant is disabled (variable or flag true, stored setting false), the server sets chats_localai_admin to off and logs one warning. The variable and the flag are an operator choice: they win over a chats_localai_admin that is on in the stored settings, at start and after a settings change or reload, so a disable never fails open. To turn the admin tools on again, remove the variable or flag. A stored localai_assistant_enabled: false with no variable or flag maps to chats_localai_admin off, and a chats_localai_admin that you set yourself in the stored settings wins over it. Use chats_localai_admin instead.

Tool groups

The assistant’s tools are two built-in tool groups of the chats, listed in the Tools menu of a chat and in Settings → Tools:

Each group has an instance setting that an administrator changes in Settings → Tools, or with POST /api/settings. Both are on by default and apply at the next turn:

Each chat has the usual switches (PUT /api/chats/{id}/builtins). A saved agent has the client group unless its builtins_off lists localai_client, and has the admin group only when its builtins_on lists localai_admin and its owner is an administrator. The tools the model sees are only the ones it can call:

• The admin group is for administrators. For any other user the group is listed as not usable, and the model has none of its tools.
• A client tool is offered when the account holds the feature permission in the table below and an installed model has the use case. A user with none of the features sees no client tool. list_models comes with them and needs no feature of its own.
• A sub-agent never has the admin group. A run that starts by itself (a trigger or a job) does not have it either.
• Messaging chats. A chat that comes from a messaging app (Telegram, Slack and so on) has the client group like any other chat, so a person can ask the bot for a picture, a sound or speech. The tools act as the owner of the chat, within the owner’s permissions and installed models, and an agent that should not spend the owner’s compute there switches the group off with builtins_off. The admin group is never offered in a messaging chat, whatever the chat or the agent switches on: the person writing may not be the owner, and the admin tools change the server. The Tools menu and GET /api/chats/{id}/tools give that as the reason. Saving a voice with voice_profile is refused there too, because the confirmation of the speaker’s consent is given in Studio.
• The client tools in a run that starts by itself need the act.spend grant, like other tools that spend compute.
• describe_image and transcribe_audio stay in the Images and audio group of the chat, so a chat never has the same tool name twice. There they are aliases of the client tools of the same name: they use the helper models of Chat image model and Chat transcription model and read the files the chat can see, then run the same code as the client tools, as the person who is chatting.

Tool search

Every tool the model is offered is sent to it again on every turn, and the two groups are large: together about 9,000 tokens. On a model with a small context window that leaves little room for the conversation. So a chat can send three small tools in place of the two groups, and the model finds and runs the group tools through them:

The three together are under 400 tokens. The setting chats_tool_search decides when a chat uses them:

• auto (default): when the schemas of the tools of both groups that the chat would send reach a tenth of the context window of the chat’s model. The window is the chat’s own context size setting, or else the context size of the model. If the window is not known, the groups are sent in full.
• on: always, when the chat has at least one tool in the groups. The tools of the user’s MCP connectors (the Connectors page) go behind the three tools too.
• off: never. Every tool is sent in full.

The tools of MCP connectors load on demand only with on. With auto and off they are sent in full, as before. With on, a chat with many connectors sends the three tools instead of every connector schema on every turn: tool_call runs the connector tool the chat would have offered, so the switches of the chat, the grants of a saved agent and the act.spend rule apply in the same way. The MCP servers of the model’s own configuration are not affected.

The decision uses only the tools the chat would send and the window, so a chat gets the same answer on every turn. It changes only when you change the switches of the chat or the model.

Permissions do not change. tool_call runs the same tool a direct call would, with the same checks: the role, the switches of the chat, the ceiling of a saved agent, the act.spend rule of a run that starts by itself, and the account of the person who is chatting. tool_search and tool_describe list and describe only tools the chat could call. Any other name, whether the tool exists or not, gets the same answer: no such tool. The tools of other groups, like the file and web tools, are always sent in full; so are the tools of MCP connectors unless the setting is on. The tools panel (GET /api/chats/{id}/tools) marks a group that loads on demand with deferred: true, and the Tools menu shows it as “Loaded on demand”.

The OpenAI-compatible API is not changed: metadata.localai_assistant still gives an administrator the admin tools there, and the client tools are not offered.

Security model

• Only an admin can start an assistant chat or have the admin tools in any chat, and the server checks the role again on every turn (defense in depth). A user who loses the admin role also loses the tools in their existing chats.
• The Home entry is hidden for non-admin users and while the setting is off.
• The tool server is in-process - there is no localhost loopback, no synthetic API key, and no extra TCP socket.
• Mutating tools (install_model, delete_model, edit_model_config, upgrade_backend, …) are guarded by a system-prompt rule that requires the LLM to confirm the action with the user before calling them. There is no separate code-side preview/apply step.

Standalone stdio MCP server

You can run the same admin tool surface as a stdio MCP server pointed at any LocalAI HTTP API:

local-ai mcp-server --target http://remote.localai:8080 --api-key <admin-key>
# read-only mode - skips registration of every mutating tool and of the client tools that write files or make content
local-ai mcp-server --target http://remote.localai:8080 --read-only

Useful for hooking LocalAI admin into Claude Desktop, Cursor, or any MCP host. The tool catalog is identical to the in-process variant, including the client tools.

Tool catalog

Read-only: gallery_search, search_models, inspect_remote_model, list_installed_models, list_galleries, get_job_status, get_model_config, list_backends, list_known_backends, list_backend_library_updates, backend_updates, system_info, list_nodes, list_scheduling, get_scheduling, vram_estimate, get_branding, get_usage_stats, get_pii_events, get_middleware_status, get_router_decisions, get_router_corpus_stats, list_shared_folders, list_shared_folder_events, list_chat_tools, list_host_exec_events, get_chat_egress, list_egress_events, list_aliases, list_failover_chains.

For a remote instance, list_installed_models returns model names, backends, capabilities, and disabled and pinned states. Set its optional capability argument, such as tts, to filter the results. The system_info tool returns the instance version, installed backends, and loaded models.

Mutating (require user confirmation per the assistant’s safety prompt): install_model, import_model_uri, delete_model, edit_model_config, reload_models, cancel_model_load, load_model, install_backend, upgrade_backend, install_library_backend, toggle_model_state, toggle_model_pinned, set_branding, set_alias, seed_router_corpus, clear_router_corpus, create_shared_folder, rename_shared_folder, delete_shared_folder, restore_shared_folder, set_shared_folder_member, remove_shared_folder_member, set_node_vram_budget, set_scheduling, delete_scheduling, pin_failover_target, unpin_failover_target, set_chat_egress_ceiling.

backend_updates lists the gallery and library backends that have a newer build and, with action check, checks the registries now (it installs nothing; taking an update stays upgrade_backend or install_library_backend, with confirmation). list_backend_library_updates and install_library_backend read and install the backends of the add-on libraries. list_chat_tools lists the built-in chat tools (bash, web_search, web_fetch), who serves each and the add-ons that replace them, and list_host_exec_events reads the audit of the commands the built-in bash ran on this machine. get_chat_egress and list_egress_events read the network settings of the Sandbox commands and their audit, and set_chat_egress_ceiling sets the widest network preset a chat may use.

Some administrator actions have no tool on purpose, and stay a person’s act in the web interface: the oversight of other users’ saved agents, triggers and connectors (list, runs, disable, delete), the Test search button of the web tools, and the settings chats_host_exec, chats_tool_providers, chats_egress_allow_private, the chats_web_* settings and the sandbox profile policy (sandbox_profiles, an owner setting of the Sandbox add-on, changed on its Settings tab). The list with the reasons is adminRoutesWithoutTool in core/services/localaitools/coverage_test.go.

The shared folder tools manage the shared folders. These tools do not carry a user into the shared folder service: a folder the assistant creates has no member until you add one, and the audit names its changes @assistant, not the administrator who asked. The other admin tools that depend on the caller, such as the usage tools, act as the administrator whose chat (or realtime session) runs them, so they see what that person may see. In a realtime session the switch chats_localai_admin and the administrator role are checked again before every tool call.

The prompt and the recipes

The admin tools come with a system prompt: the role, the safety rules (confirm before changing anything) and, for the tasks that have steps, a set of recipes such as “install a chat model”, “upgrade a backend” or “manage shared folders”. The chats send this prompt on every turn, so it is short. It holds the role, the safety rules and a list of the recipe names with one line each. The text of each recipe is a built-in skill named localai-admin-<recipe> (for example localai-admin-install-chat-model) that the model loads by name when a task matches. The skills are listed only in a chat that has the admin tools: an administrator’s chat with the LocalAI admin group on. A user who is not an administrator, a sub-agent, a messaging chat, a run that starts by itself and a chat with the group off never see their names or text. An add-on cannot replace them.

The safety rules never move into a skill. Measured on the shipped recipes, the prompt of an administrator’s chat is about 4,300 bytes instead of 25,000 (about 1,070 tokens instead of 6,250), and the full recipe text costs tokens only on the turns that load it.

The standalone local-ai mcp-server has no skills layer, so it sends the full prompt: the role, the safety rules, the tool catalog and every recipe inline. Both forms come from the same files.

Client tools

Besides the management tools above, the server registers a second group, the client tools. They run inference, so a person can ask for a picture, a recording or a ranking in a chat. The management tools are for administrators. A client tool acts as the user who calls it, like any other API request: the route checks the account’s permission for the feature, the model allow-list and the quota apply, and the usage is logged for that user. When the server refuses, the tool tells the person which capability the account may not use.

generate_video converts size to the width and height of the route, and seconds times fps (24 when unset) to num_frames, because the route does not read size or seconds. It also takes start_image, end_image, audio, ref_images, ref_audios, ref_videos (each one a list of frame image files with an optional fps and audio), seed, cfg_scale and steps. The files come from the chat’s file store and travel as data URLs; the tool never sends a path, and it does not expose the free-form backend params of the route, because some backends read file paths from them. The route accepts at most 16 references of each kind, 512 frames per reference video and 128 MiB per file; the tool stops a call whose media weigh more than 256 MiB together.

detect takes points (flat x, y, label triples, label 1 or 0) and boxes (flat x1, y1, x2, y2 quads), up to 64 of each, as prompts for segmentation models. voice and face with verify take anti_spoofing; the face route then answers a liveness verdict and score for each image, and the tool returns them. The identify routes take a store field that their handlers do not read, so the tools leave it out.

voice_profile create takes a description and, next to the first audio and transcript, extra_clips (more clips of the same voice, each with its own transcript; at most 10 clips in all). The confirmation card lists every clip, and the confirmation pins all of them together: the size and duration are the totals, and the hash covers every clip in order, so a clip that changes after the person confirmed stops the creation.

Which model a tool uses. When the call names no model, the tools generate_image, speak, transcribe_audio, embed, rerank, generate_video and describe_image use the user’s default for that kind of work, from defaults.json (see Make LocalAI yours), through one function (Inference.choose in core/services/localaitools/defaults.go), in this order: a model in the call; the default model, when it is installed; otherwise, with no default, the first installed model with the use case. A default of "ask" or a default that is not installed or is switched off stops the call with a message that tells the model to ask the user and call again with model; it never uses another model by itself. When a default decided, the result has a model_note (“Using flux.1-schnell, the user’s default for images.”) that the model repeats to the user. The other tools (detect, generate_sound, upscale_image, transform_audio, voice, face) have no default and keep the first-installed rule.

speak also takes sample_rate (8,000 to 192,000 Hz), which the TTS route passes to the model.

generate_sound takes the fields of the route: lyrics, instrumental, caption, bpm, keyscale, timesignature, language, vocal_language, think, do_sample, prompt_influence (the sampling temperature) and expansion_model, a model that expands the text first. Which of them a model reads depends on the model. The API does not accept a source audio on this route, so the tool has none. The model allow-list of the account applies to expansion_model too.

generate_image repaints the white area of mask in image when you give both. Otherwise it makes new images: image alone is the starting picture (img2img), ref_images are reference pictures for models that take them, and seed repeats a result. The tool sends these as the file, ref_images and seed fields of the generations route. voice and face take an action, verify (are these two the same?) or identify (who is this closest to?); verify needs a second file (audio2 or image2). The tools stay few and short on purpose: every tool of the group is sent to the model on every turn, so related operations share one tool.

upscale_image takes image, scale (1 to 16, and the factor the upscaler model was built for) and an optional model with the upscale use case, and saves the enlarged image as a file.

transform_audio takes audio, an optional reference, model, response_format (wav, mp3, ogg, flac), sample_rate (8000 to 192000) and params. The reference is the far-end loopback for echo cancellation, or the target speaker for voice conversion. params is forwarded to the backend by the route, so the tool accepts only a short list of keys and checks each value: noise_gate (true or false), noise_gate_threshold_dbfs (a number from -120 to 0), stem and language (a short name, never a path) and text and target_text (plain text of up to 2000 bytes). Any other key is refused with the list of allowed ones. A model that separates sources (for example htdemucs) returns one file per stem in stems; the stem that the response body carried shares its file with audio, and the tool fetches at most 16 stems, only from the generated-audio folder of the server. See Audio Transform for the route and the models.

list_models is how the model finds the name to give as model. It lists the models the account may use, by name, with their capabilities (image, tts, transcript, sound_generation, embeddings, detection, video, rerank, upscale, audio_transform, chat and others) and a short description when the model configuration has one. The optional capability argument narrows it, and query keeps the models whose name or description contains the text (any case); a few synonyms work (speech, transcription, music, embedding, upscaling, denoise, separation). It works for every user, not only administrators, because it reads GET /v1/models/capabilities as the account: the model allow-list of the account applies, and the answer has no file paths or settings. It sorts by name without regard to case and returns at most 60 models per call. offset and limit page through the list like a file read. The result gives total, offset and returned, and when more models remain a hint names the next call, for example offset=60. An offset past the end gives an empty list and a hint, not an error. It is offered together with the other client tools, and needs no feature permission and no installed model of its own. It differs from the administrator tool list_installed_models, which shows the instance’s configuration (backend, pinned and disabled state) for all models.

Every tool takes an optional model. When you leave it out, the tool uses the first installed model, by name, that has the use case. If there is none, the tool answers no <capability> model installed. describe_image uses the model that the Chat image model setting names, or an installed model that can look at images.

Files. A tool never carries file contents. A file argument (the image to edit, the recording to transcribe) is a reference, and a result (an image, audio, a video, the vectors of embed) is saved as a file and returned as a reference with its type, size and, for an image, its dimensions. In the assistant chat, a reference is a path in the user’s files: /workspace/home/..., or a path relative to the home folder. Results go to the generated folder of the home folder. A chat of an agent that works in a folder reaches only that folder, exactly as the chat’s own file tools do: a reference outside it is “file not found”, and results go to the generated folder inside the agent’s folder (or the chat’s own folder when the agent’s folder is read-only). The size limits are 20 MB for an image and 100 MB for a recording. A reference can also be a data: URL.

Limits. A tool refuses a request that is too large, with an error that states the limit: steps up to 150, n up to 4, video seconds up to 30 and fps up to 60, sound duration_seconds up to 600, top_k up to 50, up to 1000 documents for rerank and up to 256 texts for embed, and at most 1 MiB of text together for either. A user can have two image, upscale, audio-transform, video, sound or speech calls running at once; a third answers “busy” and the model can try again later.

speak does not take an uploaded reference recording, because the speech route does not. To speak in a cloned voice, save a voice profile with voice_profile and pass its voice value (a localai://voice-profiles/... reference) to speak.

Voice profiles. voice_profile keeps the voice-cloning profiles of the user who calls it, through the same routes as the voice library, so the ownership rules apply: list shows the user’s own profiles and the instance-wide ones (the result says that profiles created by an administrator are visible to all users, and it has the shape {"profiles": [...], "note": "..."}), delete removes one of the user’s own (an administrator can delete any), and the profile of another user answers “no such profile”. create takes name, audio (a reference to a WAV file in the user’s files, 1 to 120 seconds), transcript (the exact words in the clip) and, optionally, language. It answers with the id and the voice value to give to speak. A user who is not an administrator may keep at most 100 MiB of reference audio in total. speak refuses a voice that is a file path for such a user, and says to use a voice of the model or one from voice_profile. A file that is not WAV is refused with a message that says so; the tool does not convert audio.

Cloning a voice without the consent of the speaker is abuse, so a model cannot create a profile alone. In a chat, create becomes a proposal: the chat shows a card with the name, the file, the transcript and the size, duration and first 8 hex characters of the SHA-256 of the recording, and the profile exists only after the person confirms that the speaker agreed. The server pins the recording at proposal time: when the person confirms, it reads the file again and refuses to create the profile if its SHA-256 or size changed. Then the model calls voice_profile with list to read the voice value. A run that starts by itself (a trigger or a job), a sub-agent and a messaging chat have nobody to confirm in Studio, so create is refused there. A run that starts by itself also refuses delete, whatever it holds; list works without act.spend, and delete works in a chat the person watches. Outside the chats, the standalone MCP server and the OpenAI-compatible chat endpoint cannot give the confirmation, so create answers that a person must confirm: make the profile in the Voice library instead. The tool needs no installed model.

The localai skill. The chats do not carry the usage notes of these tools in every prompt. The built-in skill localai has them: which tool to use for a task, the voice-cloning steps, how to chain tools (describe an image, then speak the description) and what to tell the person when a model is not installed (no model), a permission is refused (403) or a limit is hit (429). The model loads it by name when a task needs it. A chat lists the skill only while it has the client group.

describe_image and transcribe_audio also exist as built-in chat tools that read the user’s files. A chat sends the model one tool of each name: in a chat, the Images and audio group serves these two, and the LocalAI client group serves the others.

--read-only also leaves out the client tools that write files or make new content: generate_image, generate_video, generate_sound, upscale_image, transform_audio, speak, embed, and the create and delete actions of voice_profile. The analysis tools (transcribe_audio, describe_image, detect, rerank, voice, face) and voice_profile list stay. In the standalone server, files are read from and written to the folder of --files-dir, and a file argument must lie inside it. There is no default folder: without --files-dir (or LOCALAI_MCP_FILES_DIR) the client tools that read or write files are not registered, and only rerank and voice_profile list and delete remain:

local-ai mcp-server --target http://remote.localai:8080 --api-key <key> --files-dir ./media

A user’s API key is enough for the client tools. The management tools still need an administrator key.

Adding new tools or skills

The MCP server lives at core/services/localaitools/. Tools are registered in tools_*.go; skill prompts (the markdown the LLM sees) are embedded from prompts/: one file per recipe under prompts/skills/, sent inline by the standalone server and offered as a skill by the chats. To add a new admin tool, add a method to the LocalAIClient interface plus implementations in inproc/ and httpapi/, then register the tool and add or update a skill prompt. See .agents/localai-assistant-mcp.md for the full contributor checklist.

Terminal agent

local-ai chat opens a terminal agent that runs against your LocalAI server. It is not a separate tool: the agent is compiled into the local-ai binary, so if you have LocalAI you already have it.

It works in the shell you already have open. It reads your files, runs commands on your machine, delegates to sub-agents, and loads MCP servers, plugins and skills. Read-only work happens on its own; anything that can change something asks you first.

The agent is nib embedded in LocalAI, which is why its plugin, skill and MCP ecosystem works here unchanged.

Start a session

# Terminal 1
local-ai run

# Terminal 2
local-ai chat

That opens the full-screen interface. Pass --cli for a plain, pipe-friendly session instead.

If nothing is listening, an interactive session offers to start a server for you and stops it again when you exit. Anywhere else, for instance in a script, it fails and points you at local-ai run.

How the model is chosen

The agent picks the model in this order, and stops at the first one that answers:

1. --model, if you passed it.
2. The model saved in the agent’s config.
3. The only model the server offers, when there is exactly one.
4. An interactive picker, when there are several and you are at a terminal. Your choice is saved, so the question is asked once.
5. Otherwise it fails, listing the models the server does offer.

Summon it with Ctrl+Space

local-ai chat --init prints a shell widget that binds Ctrl+Space to the agent, so you can call it from a half-typed command line without losing what you were doing:

# zsh
echo 'eval "$(local-ai chat --init zsh)"' >> ~/.zshrc
# bash
echo 'eval "$(local-ai chat --init bash)"' >> ~/.bashrc
# fish
echo 'local-ai chat --init fish | source' >> ~/.config/fish/config.fish

Inside a session

• /models lists the models the server offers, marking the one you are using.
• /model <name> switches model and keeps the conversation you are in.
• /compact summarises the history so far to free up context.

Tool approval

Read-only tools run without asking. That covers reads and searches, and read-only shell commands such as ls and cat, so the agent can look around and answer you without interrupting. Everything else prompts for approval, and you can approve, deny, or trust the tool for the rest of the session.

nib’s README keeps the exact list of what counts as read-only, along with the approval modes you can set in the agent’s own config.

--yolo, or LOCALAI_CHAT_YOLO=1, approves every tool call without asking. It is the right setting for a sandbox and the wrong one for your laptop.

Piping and scripting

--cli makes the agent answer a piped question and exit:

echo "what is 2+2" | local-ai chat --cli

That exits 0. Read-only tools still run, so a piped question can inspect a repository or a log file to answer you.

A tool call that is not read-only is a different matter: there is nobody at the keyboard to approve it, so the call is denied and the session exits 3. The code is deliberately not 1, so a script can tell “I refused to act” apart from “I crashed”.

Pipe a question in without --cli and the agent refuses, with a message naming --cli. It will not render a full-screen interface into a pipe that cannot show it.

Redirecting the output is not the same thing and is not refused: local-ai chat > out.txt from a terminal draws the interface on /dev/tty and writes only the command you pick with Ctrl+Y to the file. That is the same capture the Ctrl+Space widget is built on, so both work. It is the stdin that has to be a terminal.

Where the agent keeps its state

Config, plugins and skills live in ~/.config/localai/chat/, or under $XDG_CONFIG_HOME when you have set it. Override it with --config-dir, or with LOCALAI_CHAT_CONFIG_DIR. The directory is user-scoped rather than server-scoped, because the agent is a client and may be pointed at a remote LocalAI.

Plugins, skills and MCP servers

The agent’s own management commands are reached by passing them through:

local-ai chat plugin install https://github.com/user/plugin
local-ai chat skill list
local-ai chat mcp add my-server -- npx -y @modelcontextprotocol/server-filesystem /tmp

Everything after the first positional argument is forwarded verbatim, so LocalAI’s own flags have to come first:

local-ai chat --config-dir /srv/agent plugin list

Claude Code plugins install as they are, so a plugin written for that format needs no conversion.

Flags

Every flag, with its environment variable, is in Chat flags.

Model Context Protocol (MCP)

LocalAI supports the Model Context Protocol (MCP). MCP connects models to external tools and services. Your models can use MCP servers to get live data, call APIs and use specialised tools.

What is MCP?

The Model Context Protocol is a standard for connecting AI models to external tools and data sources. It enables AI agents to:

• Access real-time information from external APIs
• Execute commands and interact with external systems
• Use specialized tools for specific tasks
• Maintain context across multiple tool interactions

Key Features

• Real-time Tool Access: Connect to external MCP servers for live data
• Multiple Server Support: Configure both remote HTTP and local stdio servers
• Cached Connections: Efficient tool caching for better performance
• Secure Authentication: Static bearer tokens or OAuth2 client_credentials with automatic token refresh
• Multi-endpoint Support: Works with OpenAI Chat, Anthropic Messages, and Open Responses APIs
• Selective Server Activation: Use metadata.mcp_servers to enable only specific servers per request
• Server-side Tool Execution: Tools are executed on the server and results fed back to the model automatically
• Agent Configuration: Customizable execution limits and retry behavior
• MCP Prompts: Discover and expand reusable prompt templates from MCP servers
• MCP Resources: Browse and inject resource content (files, data) from MCP servers into conversations

Configuration

MCP support is configured in your model’s YAML configuration file using the mcp section:

name: my-mcp-model
backend: llama-cpp
parameters:
  model: qwen3-4b.gguf

mcp:
  remote: |
    {
      "mcpServers": {
        "weather-api": {
          "url": "https://api.weather.com/v1",
          "token": "your-api-token"
        },
        "search-engine": {
          "url": "https://search.example.com/mcp",
          "token": "your-search-token"
        }
      }
    }

  stdio: |
    {
      "mcpServers": {
        "file-manager": {
          "command": "python",
          "args": ["-m", "mcp_file_manager"],
          "env": {
            "API_KEY": "your-key"
          }
        },
        "database-tools": {
          "command": "node",
          "args": ["database-mcp-server.js"],
          "env": {
            "DB_URL": "postgresql://localhost/mydb"
          }
        }
      }
    }

agent:
  max_iterations: 10             # Maximum MCP tool execution loop iterations

Configuration Options

In the interactive model editor, Remote MCP Servers and MCP STDIO Servers are YAML editors. Enter only the embedded mcpServers document shown inside the remote: | or stdio: | block above; the editor supplies the outer model configuration keys.

Remote Servers (remote)

Configure HTTP-based MCP servers:

• url: The MCP server endpoint URL
• token: Static bearer token for authentication (optional)
• oauth2: OAuth2 client_credentials settings (optional, mutually exclusive with token); see OAuth2 client credentials

LocalAI automatically selects the transport for remote model MCP servers. It tries Streamable HTTP first, including servers that do not assign session IDs. If the initial POST returns HTTP 400, 404, or 405, LocalAI retries with legacy SSE. Both attempts share the discovery timeout and use the configured bearer token. Authentication failures and redirects do not trigger fallback.

Use the endpoint URL published by your server: usually /mcp for Streamable HTTP or /sse for legacy SSE. Legacy SSE servers must advertise a message endpoint on the same origin (scheme, host, and port). No transport setting is required.

Remote model MCP connections originate from the LocalAI process. If LocalAI runs in Docker, the URL must therefore resolve and be reachable from the LocalAI container, not only from the host browser. For another service in the same Compose project, use its Compose service name and container port. Host-only DNS names, VPN DNS, and private routes must also be made available inside the container.

OAuth2 client credentials for remote servers

When an MCP server sits behind an OpenID Connect / OAuth2 provider (for example authentik, Keycloak, Entra ID or Auth0), LocalAI can obtain short-lived access tokens with the client_credentials grant instead of using a long-lived static token:

mcp:
  remote: |
    {
      "mcpServers": {
        "internal-tools": {
          "url": "https://mcp.example.com/mcp",
          "oauth2": {
            "token_url": "https://auth.example.com/application/o/token/",
            "client_id": "localai",
            "client_secret_env": "MCP_INTERNAL_TOOLS_SECRET",
            "scopes": ["mcp:tools"],
            "endpoint_params": {"audience": "mcp-gateway"}
          }
        }
      }
    }

Behaviour:

• The token is fetched on the first request to the server, cached, and sent as Authorization: Bearer <token> on every request, for both streamable HTTP and SSE transports.
• It is refreshed proactively once half of its lifetime (expires_in) has elapsed. If the provider omits expires_in, a lifetime of 5 minutes is assumed.
• If a refresh fails, the current token keeps being used until 30 seconds before it expires (retries wait at least 5 seconds after a failed fetch, including the first fetch). After that, requests to the MCP server fail with an error; LocalAI never falls back to an unauthenticated request.
• Configuring both token and oauth2 for the same server is rejected when the model configuration is loaded, as are missing or duplicated client_id/client_secret sources. An environment variable named in *_env that is unset or empty makes the connection to that server fail, and the server is reported with an error in the server listing.
• Debug logs of remote server entries redact static tokens and OAuth2 client secrets in both text and JSON formats.
• Token caches and retry timers are local to each connection-owning process. Workers obtain and refresh their own tokens; this cache is not shared across the cluster.
• The environment variables are read by the process that connects to the MCP server. In distributed mode that is the agent worker, so set them there.
• Sessions and cached tokens are keyed by the server configuration, not by the value of an environment variable. After you rotate a secret that is referenced by client_secret_env (or client_id_env), restart the process that connects to the MCP server so it picks up the new value.

Servers configured with a static token behave exactly as before.

STDIO Servers (stdio)

Configure local command-based MCP servers:

• command: The executable command to run
• args: Array of command-line arguments
• env: Environment variables (optional)

Automatic activation (auto)

/v1/chat/completions only runs a model’s MCP servers when the request selects them through metadata.mcp_servers. Plain OpenAI clients cannot send that field. Set auto: true in the mcp: block to enable every configured server when the request names none:

mcp:
  auto: true
  remote: |
    {"mcpServers": {"weather-api": {"url": "https://weather.example.com/mcp"}}}

A request that does send metadata.mcp_servers still gets exactly the servers it names. /v1/responses already enables all servers when the request sends no tools, and /mcp/v1/chat/completions always does; auto does not change them.

auto only applies when MCP is enabled on the instance (not disabled with LOCALAI_DISABLE_MCP) and, with authentication on, the caller has the mcp permission. Otherwise the request is answered as a plain chat: no server is contacted and no tools are added. It is not rejected, because the client did not ask for MCP.

Client tools (client_tools)

client_tools: drop (a top-level model config key) discards the tools, functions and tool_choice a client sends, so the model is offered only its own MCP tools. Use it when a front end attaches tools of its own that should not reach this model. Empty (the default) keeps client tools.

On a model alias these keys go inside the alias’s profile block, which lets several assistants with different tools share one loaded model.

Agent Configuration (agent)

• max_iterations: Maximum number of MCP tool execution loop iterations (default: 10). Each iteration allows the model to call tools and receive results before generating the next response.
• max_attempts: How often a failed tool call is retried (chats and saved agents).
• force_reasoning_tool: Make the model reason before it picks a tool (chats and saved agents).
• max_generation_tokens: Accepted and ignored. It capped the completions of the old agent jobs.

The planning, plan re-evaluation, loop detection and reasoning switches of the old agent loop (enable_planning, enable_plan_re_evaluator, enable_reasoning, enable_mcp_prompts, disable_sink_state, loop_detection, max_adjustment_attempts) are ignored; a model file that sets one still loads and the server logs a warning. See Model configuration.

Agent-scoped MCP servers

The mcp: block above attaches MCP servers to a model: every request that uses that model config can reach those tools. A saved agent of the chats can limit a chat to some of them: its mcp_servers list names the servers of the model’s mcp: block that the chat may use. The agent cannot add a server of its own.

Usage

Selecting MCP Servers via metadata

All API endpoints support MCP server selection through the standard metadata field. Pass a comma-separated list of server names in metadata.mcp_servers:

• When present: Only the named MCP servers are activated for this request. Server names must match the keys in the model’s MCP config YAML (e.g., "weather-api", "search-engine").
• When absent: Behavior depends on the endpoint:
  • OpenAI Chat Completions and Anthropic Messages: No MCP tools are injected (standard behavior).
  • Open Responses: If the model has MCP config and no user-provided tools, all MCP servers are auto-activated (backward compatible).

The mcp_servers metadata key is consumed by the MCP engine and stripped before reaching the backend. Clients that support the standard metadata field can use this without custom schema extensions.

API Endpoints

MCP tools work across all three API endpoints:

OpenAI Chat Completions (/v1/chat/completions)

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-mcp-model",
    "messages": [{"role": "user", "content": "What is the weather in New York?"}],
    "metadata": {"mcp_servers": "weather-api"},
    "stream": true
  }'

Anthropic Messages (/v1/messages)

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-mcp-model",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What is the weather in New York?"}],
    "metadata": {"mcp_servers": "weather-api"}
  }'

Open Responses (/v1/responses)

curl http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-mcp-model",
    "input": "What is the weather in New York?",
    "metadata": {"mcp_servers": "weather-api"}
  }'

The tools LocalAI runs server-side are part of the response: output lists a function_call item and its function_call_output item for every MCP tool call, in the order they ran, before the final message. Replayed tool results retain the call_id association with their calls. If the streaming iteration limit is reached, each executed tool round appears once in the final output. This holds for streaming (response.completed) and non-streaming requests and for the stored response. A follow-up request with previous_response_id therefore replays the earlier tool calls and results to the model, and a client that keeps the output items and sends them back as input does the same. Without this trail, models tend to answer follow-up questions from the earlier text instead of calling the tool again. Chat completions (/v1/chat/completions) return only the final answer, so a client cannot carry the tool trail over to the next turn there.

Server Listing Endpoint

You can list available MCP servers and their tools for a given model:

curl http://localhost:8080/v1/mcp/servers/my-mcp-model