Frequently asked questions

Yes. Loach is open source under the MIT license. There are no subscriptions, paywalled features, or usage limits inside the app. If you connect to a paid endpoint (e.g. OpenAI), you pay them for tokens - Loach itself is free.

Native desktop apps for Windows, Linux and macOS (Apple Silicon, macOS 11 or later with Safari 16.4 or later) are published with every release. The macOS build is not Apple-notarized, so first launch needs a one-time Gatekeeper bypass - see Installation → macOS. Intel Macs are not supported.

No, not on its own. There is no telemetry. The only outbound requests Loach initiates are the ones you set up: generations against the remote provider you configured - including whatever goes into the prompt, such as your memories, Library sources and files the model reads from a chat’s folder - the text sent to a Library embedding model on a remote endpoint, model pulls you start, web fetches and Library links you add, MCP servers you turned on (the first run of an npx or uvx server downloads its package), and the update check - run manually from Settings → Updates, or once per launch if you opted into the auto-check. With a purely local provider like Ollama, Loach works fully offline. See Storage & privacy.

Only when you ask. Settings → Updates has a manual Check for updates button and an opt-in Auto-check for updates switch that looks once per launch and shows an Update available dialog with the release notes. Nothing downloads until you pick Update now (or Install update in the panel). In-app updates work on Windows, all three Linux formats and macOS - see OTA updates.

Builds target glibc 2.35, so Ubuntu 22.04 and Debian 12 are the oldest supported releases; anything newer works. Pick .deb, .rpm or .AppImage - all three update in-app.

In a SQLite database at <app-data-dir>/loach.db, attachments included:

• Windows: %APPDATA%\dev.loach.app\loach.db
• Linux: ~/.local/share/dev.loach.app/loach.db
• macOS: ~/Library/Application Support/dev.loach.app/loach.db

No. Loach is the workspace; the model is supplied by a provider. Install Ollama and pull a local model, or configure an OpenAI-compatible endpoint.

Anything supported by Ollama. Popular choices include Qwen, Gemma, DeepSeek, GPT-OSS, Mistral and Llama derivatives. Use the in-app Models tab to pull and manage them. If you have nothing pulled yet, the onboarding wizard recommends a model sized against your GPU’s VRAM (or system RAM when there’s no discrete GPU, and on Macs) and labels every option with how well it will run.

Yes - that’s the point. Ollama and your OpenAI-compatible endpoint live side-by-side, and you switch between them from the chat header without changing anything else.

One at a time. The base URL and API key are a single configuration in Settings → Providers. To switch from, say, Groq to OpenRouter, update the base URL and key - your existing chats are preserved.

Yes. The o-series and GPT-5 turn down some of the fields Loach sends, such as max_tokens or temperature. Loach reads the 400 error, moves max_tokens to max_completion_tokens or drops the refused field, and sends the request again - no setup needed. Servers that stream a model’s reasoning, such as OpenRouter, vLLM or Ollama’s /v1, show it in a Thinking block. See Providers → Reasoning models.

Yes - try smaller quantizations (e.g. a 4-bit 3B/4B model), and enable Low VRAM mode globally or per-chat. This sends Ollama’s low_vram flag with every request.

Yes, if the model supports tool calling. Loach ships built-in tools that run locally - calculator, date/time, counting, hashing, UUIDs, base64, JSON, unit conversion, text diff, sorting, IP maths and PDF generation - each opt-in from Settings → Tools. Give a chat a folder and the model also gets tools to work with its files. You can register MCP servers, over HTTP or as local programs, for external tools, and turn on Web fetch to have pasted URLs downloaded into the prompt.

Only the files in a folder you give the chat: click + next to the message box and choose Add directory. The model can then list, find, read and search files in that folder, and write, edit, move or delete them - but each change is shown to you first (the new contents, a line-by-line diff, from → to, or a deletion warning) and waits for your approval, unless you’ve allowed that tool for the chat.

It’s sandboxed to that folder: paths outside it, including links that point elsewhere, are refused; there’s no shell and no recursive delete; and the picker refuses a whole drive or Loach’s own data folder. Changes to what Git runs - a .git folder, the .husky and .githooks hook folders, a .pre-commit-config.yaml or a folder laid out as a bare repository - always ask. Line endings and non-UTF-8 encodings are kept as they were. With a cloud provider, files the model reads are sent to it like any other message. Private Chat never gets a folder. See Work in folders.

A Markdown file at the root of a chat’s folder holding the project’s own instructions - how to run the tests, what not to touch, house style - the same idea as a CLAUDE.md or AGENTS.md. Loach adds it to the system prompt on every turn and reads it fresh each time, so an edit applies on your next message. Up to 32 KB of it reaches the model; keep it short, since local models follow brief instructions far better. The model is told the file is the project’s text, not yours: it can’t grant permissions, and your instructions win when the two conflict. While one is present, the “Working in” notice above where you type shows a LOACHFILE.md badge. There’s a sample to start from; see also Work in folders.

So nothing runs or changes behind your back. Two kinds of calls pause the reply and show an approval card: MCP tool calls, with the server, the tool and its arguments, and the file tools that change files, with the change itself. Answer Allow once, Always allow that tool (Allow … for this chat for a file change), or Deny; a card left unanswered for 10 minutes isn’t run. While it waits, other chats queue behind it.

Asking is on by default for every MCP server, including ones you added before. To stop it for a server you trust, open it in Settings → MCP and turn off Ask before each tool call; Ask again for all in the same editor clears earlier Always allow answers. The other built-in tools, such as the calculator, never ask. See MCP support and Work in folders.

Yes. In Settings → MCP, add a server as Local process (stdio): a command (npx, uvx, node or a full path), one argument per line, and optional NAME=value environment variables. Before a local program starts - when you test it, save it switched on, change what it runs, or turn it on - a native system dialog shows exactly what will run, and only clicking Start server runs it. The runtime must be installed (Node.js for npx, uv for uvx), and startup - including a first-run package download - is allowed 60 seconds. Environment variables are stored in Loach’s database in plain text and left out of backups, and stdio servers restored from a backup arrive switched off. See MCP support.

Yes - put them in the Library. Upload files (PDF, Word, text and code, images), add links to web pages or write texts, then attach them to a chat with + → From Library or by typing #, or add them to a Space’s sources so every chat in it can use them.

Sources that fit go to the model in full; bigger ones are searched, and only the excerpts most relevant to each message are sent - the Sources chip above the message box lets you force either. Keyword search works out of the box; set an embedding model in Settings → Library to also search by meaning - with one on a local Ollama, nothing leaves your machine. Each reply shows which sources it used. For a one-off question, attaching a file to the message works too. See Library → Source modes.

They’re off by default. Turn on Settings → Features → Global memories (or the same switch in setup’s Pick your defaults step). After each reply in a chat outside a Space, Loach asks the chat’s own model to note lasting facts about you - updating or dropping ones that changed, with an Undo on every change - and adds them to every chat, Spaces included. Chats in a Space keep writing to that Space’s memory, which is on for every new Space and wins when the two conflict.

Manage global memories opens a searchable editor, and switching the setting off stops both saving and sending them. The facts go to whichever provider a chat uses, so one learned with a local model can reach a cloud one. See Memory.

It never reads or writes memory of either kind, and it gets no tools at all - neither built-in tools nor MCP - no web fetch, no Library sources and no working folder. Private Chat also offers only Ollama models, never Ollama’s cloud ones, and leaves out your Custom instructions, Space context and the date preamble. See Private Chat.

Your OpenAI-compatible API key lives in your operating system’s credential manager - Windows Credential Manager, the Linux Secret Service, or the macOS Keychain - and is never written to the SQLite database or to plain-text config. It’s only sent over https://, or over http:// to this computer. MCP servers are the exception: their headers and environment variables, which often hold keys, are stored in the database in plain text and left out of backups.

Optional PIN (4, 6 or 8 digits), password (at least 8 characters), or both. Your credentials are hashed with Argon2id and stored in the OS credential manager (separately from API keys). The plaintext is never persisted. Configure it in Settings → Security.

Not from inside Loach. There is no recovery path by design: the lock is an Argon2id hash in the OS credential manager that Loach cannot reverse, and Factory reset itself asks for your credentials. Try the hint you set when creating the lock. Otherwise, delete the lock’s entry from the credential store by hand - service dev.loach.app, account app_lock - and your chats and settings stay untouched. A marker file next to the database (app_lock.json) remembers that a lock was set, so the next launch still shows the lock screen once: enter any PIN of the right length (and any password) and Loach is unlocked from then on, or delete app_lock.json as well to skip that screen. Deleting the app data folder doesn’t help: it wipes your chats but leaves the lock. See Troubleshooting → App lock.

Yes. Once an app lock is configured, Settings → Security offers Lock after inactivity (1, 5, 15 or 30 minutes) and Lock when minimized, both opt-in. Ctrl + Shift + L (⌘ + Shift + L on macOS) locks immediately from anywhere in the app, and typing /lock in the message box does the same. On macOS, closing the window hides Loach and, with a lock set, locks it. See App lock → Auto-lock.

Open Settings → Data and use Export data. You’ll get a single JSON file containing chats, folders, Spaces (with their sources and memories), the Library, global memories, Snippets and snippet variables, MCP servers and settings. It’s tagged loach/v2, so Loach 1.5 and older can’t restore it. API keys are not in the export - they live in the OS credential manager - and neither are MCP headers, environment variables, secrets passed in a server’s arguments or address, or chats’ working folders. The same panel shows a storage breakdown, so you can see what your chats, attachments, Spaces and Library weigh before you back them up.

Install Loach on the new machine, then use Import data in Settings → Data - or Restore from backup on the onboarding wizard’s welcome screen - with the JSON file you exported from the old one. Importing replaces everything in the new database. Afterwards, re-enter your API key, any MCP headers and environment variables, and secrets left out of a server’s arguments or address, switch local (stdio) MCP servers back on - they arrive disabled - and pick chats’ working folders again; none of those travel in the export. The Library comes along, and Loach rebuilds its search index after the import.

Settings → Data → Erase… opens Erase & Reset. Factory reset wipes the database, clears every setting, and removes the API key and the app lock from the credential store; Loach then reloads into onboarding. Remove my data is the gentler option - it drops chats, folders, Spaces, the Library, memories, Snippets and MCP servers but keeps your settings and the key. Both need you to type YES, plus your current PIN or password when an app lock is set.

For Ollama: make sure the server is running and at least one model is pulled. When it isn’t running, the model picker shows Not running and a Start Ollama button, and Auto-launch Ollama in Settings → Providers starts it whenever Loach opens (both work only for an Ollama on this computer). Loach probes http://localhost:11434 on launch - if Ollama is on another host or port, update the base URL in Settings → Providers.

For an OpenAI-compatible provider: confirm the base URL (the presets next to the field fill in the common ones), that the API key is set if the endpoint needs one, and that the endpoint exposes a /models route - the picker lists only what that route returns, and has no field for typing a model ID. Test connection in Settings → Providers reports the model count or a readable error.

Try a smaller model or a more aggressive quantization. Turn on Model preloading so the first request doesn’t wait on a cold start, and raise Keep model loaded in Settings → Features so it stays resident between prompts. Enable Low VRAM mode if you’re memory-constrained. For Ollama-side levers such as flash attention and KV-cache quantization, see Performance & VRAM.

Each reply gets at most 10 rounds with the model, so a model stuck in a loop can’t run forever: tools can run in the first nine, and the last round goes out without tools so the model can wrap up. This error means it asked for tools anyway, and those calls weren’t run. Send a follow-up such as “continue” to give it another 10 rounds, or break the task into smaller requests. With a working folder, pointing the model at the right files up front - or in LOACHFILE.md - saves rounds spent searching.

That usually means the model output isn’t well-formed Markdown. Lower the temperature, or add an explicit instruction like “Reply in valid GitHub-flavoured Markdown”. Loach uses remark-gfm + rehype-highlight under the hood, so anything valid will render.

Single-dollar spans are treated as currency unless they clearly read as math, and TeX that doesn’t parse shows its own source on purpose. Ask the model for $$…$$, \(…\) or a ```math fence. See LaTeX math and Troubleshooting.

Loach scales images down before sending them - by default to 1024 px on the longest side - because a full-size photo costs thousands of image tokens and many local models read it worse, not better. The stored image stays the original. For more detail, raise the limit or choose Original: for one chat in the parameters panel’s Images section, for a Space on its Settings tab, for Library images in Settings → Library, or as the default for everything in Settings → Features → Image scaling. Private Chat uses the Settings → Features one. See Attachments → Image scaling.

Open an issue on the GitHub repository: github.com/ztcs-software/loach/issues. Please include your OS, Loach version, and steps to reproduce.