← All features

Onboarding wizard

A six-step wizard runs on first launch and after a factory reset. Each step saves its own choices before moving on, so closing the wizard part-way still leaves the app in a consistent state - you can finish setting things up from Settings later.

The steps

• 1. Welcome - Welcome to Loach with a Get started button, plus Restore from backup for anyone arriving from another install with a full export in hand. Restoring replaces the app’s data with the backup’s and reloads Loach, which then skips the rest of the wizard.
• 2. Pick a provider - the only required step. Choose Ollama (local, marked Recommended) and, if you have no models yet, pull one sized to your machine - or OpenAI API for a cloud API or a local OpenAI-compatible server. A Provider switch flips between the two once you’ve picked. Continue stays disabled, with a hint beside it, until Ollama has a model (or one is downloading) or the endpoint is verified. It sits second so a model download has the rest of the wizard to make progress.
• 3. Pick your defaults - Global memories, Temporal awareness, Thinking and Low VRAM mode. Whatever the switches show is saved whether you press Continue or Skip.
• 4. Give the model some tools - Web fetch, a row for MCP servers with no switch (it explains them and points you to Settings → MCP), and the thirteen built-in tools, with a switch per tool and All OFF / Recommended / All ON presets. Collapse the list and its footer still says how many are on.
• 5. Add custom instructions - the global Custom instructions textarea. Whatever you type here becomes the system prompt for every new chat unless a Space or per-chat override wins. Display an example shows a starter prompt with a Use this example link, and lists the template variables {{CURRENT_DATE}}, {{CURRENT_TIME}} and {{USER_NAME}}. Continue saves the text; Skip leaves your instructions as they were.
• 6. Final - You’re all set and a Start chatting button. You land in a fresh chat with the model dropdown auto-opened so you can pick a model and start typing immediately. If a model is still downloading, the screen says Setup complete instead, promises to tell you when the model is ready, and the button reads Explore Loach.

Every step after the welcome screen has a Back button (on Pick a provider, only until you’ve chosen a path), and dots along the bottom show how far along you are.

The wizard does not ask for a display name. {{USER_NAME}} still resolves from Settings → General; it simply is not collected up front, because the value only pays off once you write it into a custom instruction.

Recommended defaults

• Global memories - off. When on, every reply triggers a second, hidden call to the chat’s model that notes lasting facts about you, and those facts go with every chat - local or cloud provider alike. Private Chat never uses memory. See Memory.
• Temporal awareness - on. Every chat gets the current date, weekday and timezone so the model can answer “what day is it?” correctly.
• Thinking - on. This is the default for the per-chat Thinking toggle. It only affects thinking-capable Ollama models; other providers ignore it.
• Low VRAM mode - off. When on, it forces Ollama’s low-VRAM mode for every chat, overriding the per-chat toggle. Only enable it if your machine is constrained; OpenAI-compatible providers ignore it.
• Built-in tools - the Recommended preset: everything on except the four only a developer asks for (Hash, UUID, Base64, IP / CIDR) and Workspace files, which switches itself on the first time you add a folder to a chat. Because the screen shows a selection, Continue saves the tools exactly as displayed, while Skip saves only what you explicitly flipped - skipping past is not consent to the recommended set.
• Web fetch - off. It is exempt from the presets and only ever saved when you touch it, being the one switch here that reaches the network on your behalf.

Choosing a model

When Ollama is running but has no models, the provider step reads your machine’s capacity and leads with a single Recommended for this machine card - the largest catalog entry that runs comfortably and fits your free disk space - with a Pull this one button, instead of asking a newcomer to pick blind from a dozen tags. When nothing runs comfortably it suggests the smallest download that fits on disk, and when nothing fits on disk it points at the smallest download overall. The card names the numbers it used, for example “Based on 8.0 GB VRAM · NVIDIA GeForce RTX 4060 · 120 GB free on disk”.

• Sized against VRAM whenever a discrete GPU is present, since that is what decides whether a model is usable: Ollama loads what fits on the card and runs the rest on the CPU, so a model that “fits in RAM” can still crawl. Windows reads dedicated video memory for any vendor; Linux reads nvidia-smi, then the amdgpu sysfs node (Intel Arc falls back to RAM); macOS deliberately uses system RAM, because Apple Silicon shares it with the GPU. Adapters under 1 GB - and, on Windows, any adapter that reports unified memory, and on Linux an AMD APU - count as integrated graphics and are ignored, so a Ryzen laptop is sized by its RAM rather than the small slice of it set aside for graphics. Anything unreadable falls back to RAM.
• A verdict on every row - Runs well (green, with a tick), Runs OK (fits with little headroom), Runs slowly (a dense model exceeding VRAM but fitting RAM), Too big for this machine, or Not enough disk space, which also disables that row’s Pull button. Numbers and mechanics live in the tooltips.
• Honest about architecture - the memory need is modelled, not equated with the download. Models that keep part of themselves off the accelerator (Gemma’s E-variants) are judged by their resident footprint, and mixture-of-experts models split across GPU and RAM are reported as running well, because only a few billion parameters run per token.
• A short catalog - six families (Gemma 4, Qwen 3.5, Qwen 3.6, Qwen 3.8, Nemotron 3.5 Lightning and Muse Glimmer), collapsed by default, each listing its parameter sizes with an approximate download size and a link to its ollama.com page.
• Not a restriction - every catalog entry with room on disk stays pullable, Too big for this machine included, and the Pull a custom tag field takes any tag from ollama.com/library (Have a specific tag in mind? jumps to it). The badges are advice.

If the recommendation looks wrong for your hardware, see Onboarding sized my machine wrong.

Neither provider path pins a default model silently. When Ollama already has models, the step reports how many it found and shows them in a Default model picker, pre-set to the first one unless you already have a default - one picked earlier, or a model verified on the OpenAI option, which just looking at the Ollama option doesn’t replace (the picker then reads Select a model). The OpenAI path shows the endpoint’s catalog in the same picker, pre-set to its top-ranked chat model each time you verify (see below). Either way you can change the pick here or later from the model dropdown.

Connecting an OpenAI-compatible endpoint

The OpenAI API path asks for a Base URL (defaults to https://api.openai.com/v1; change it for vLLM, LM Studio, LiteLLM or any OpenAI-compatible proxy) and an API key. The key is optional: local servers such as LM Studio usually need none, so leave it blank. Verify & save first lists the endpoint’s models with the key you typed, to prove the connection works, and only then saves the base URL and stores the key in your OS credential manager. If the check fails, the error is shown and nothing is saved, so a bad key never stays saved and never replaces a working one. On success you see Connection verified and a Default model picker ranked so chat models come first - embedding, audio, image and moderation models go to the bottom.

Come back to this step with a key already stored and Loach checks it again: Key stored - not verified yet. shows until the endpoint answers, and Continue unlocks once it does. If the stored key doesn’t work, the error says so - double-check it and the base URL.

Downloads that outlive the wizard

Starting a pull pins that model as your default and unlocks Continue right away, so you can finish setup while it downloads. A progress strip pinned to the bottom of every remaining step shows each pull, with a stop button per download - Ollama keeps the layers it already fetched, so a re-pull resumes from them. Finished pulls stay listed as Downloaded or Failed rather than vanishing. In the chat itself a banner above the composer tracks the same download, and sending to a model that is still downloading is refused with a clear “still downloading (43%)” message rather than a confusing not-found error.

When Ollama is not reachable

The provider step shows Ollama isn’t reachable with three buttons: Start Ollama, Download Ollama (opens ollama.com) and Change URL, for an Ollama on another port or machine. It offers to start Ollama before suggesting a download, since “installed but not running” and “not installed” look identical from a failed probe - if the start fails, its error (such as not finding the Ollama executable) tells the two apart. Loach can only start Ollama on this computer. The panel also re-checks every 3 seconds in the background, so if you leave to install Ollama you come back to a green panel instead of a stale warning.

Dismissing and resuming

Press Esc or click × on any step to close the wizard. On Pick a provider it asks first - Skip setup? with Keep configuring and Skip anyway - because the app needs a provider before you can chat; you can set one up later in Settings → Providers. Steps you have completed stay saved, but the step you close on is not: its switches only save on Continue or Skip. Either way you land in a new, empty chat, and the wizard does not re-appear on later launches unless you run a factory reset.