# Models

Insula runs on the models you assign. Under **Settings**, you add provider **Connections**, register models on those connections, then pick which model fills each **Active Models** role. Each role feeds a different part of the product: conversation and tools, plan execution, Insight search, and image description.

## Active Models

Open **Settings** from the top bar, then work under **Providers**.

1. Add a **Connection** for each provider endpoint (credentials and base URL as that provider requires).
2. Register models on the connection and mark their capabilities: chat, embed, or image.
3. Under **Active Models**, choose a model for each role from the models that match that role's capability.

The four roles are **Chat**, **Build**, **Embeddings**, and **Image**. Any role may be left unset. Chat and Build both draw from chat-capable models. Cloud backup can sync provider setup and Active Models preferences when you use an Insula account; Insight indexes stay on this machine and are not restored from backup.

See also [Settings spaces](/wiki/02-settings-spaces).

## Chat

**Chat** is the model for ordinary conversation and tool use. It powers:

- **Agent** turns (home companion and in-project implementer)
- **Discuss** (read-only exploration)
- Plan drafting in **Plan** mode

If **Build** is unset, Chat is also used when a finished plan is executed. For how modes behave day to day, see [Agents](/wiki/05-agents).

## Build

**Build** is the model that executes a finished plan: the edits and verification steps described in the plan document. Only chat-capable models appear in this dropdown.

Build is optional. When it is unset, Insula uses the Chat model for plan execution. Assign a separate Build model when you want a different (often stronger or cheaper) model for long implementation runs while Chat stays on a model you prefer for dialogue.

## Embeddings

**Embeddings** powers vector indexing and search for the [Insight DB](/wiki/07-insight-db). Insight needs this role so agents and the Insight view can find project content by meaning.

Without an embeddings model, project semantic search through Insight does not work.

When you change the embeddings model, every project that uses Insight must be re-indexed. Use the Insight DB view and **Re-sync** (or equivalent re-index control) on each project so the index matches the new model.

## Image Understanding

**Image Understanding** describes images so they can be included in Insight context (for example while indexing). The role is optional.

You can also turn image understanding on or off under **Settings → Projects → Insight DB → Image understanding**. Changing the image model requires restarting the app before the new assignment is used.

Image description can be expensive if it shares a large chat model. Many people assign a separate, lower-cost image-capable model for this role while Chat and Build stay on their usual models.

Insula does not use this role to generate images.

## Changing models

After you change an Active Models assignment:

- **Chat:** later Agent, Discuss, and Plan-drafting turns use the new model.
- **Build:** the next plan execution uses the new model (or Chat again if Build is cleared).
- **Embeddings:** re-index every project that relies on Insight so search stays consistent.
- **Image:** restart the app, then resume indexing or other flows that describe images.

Clearing a role leaves that capability unset until you pick a model again. Clearing Build falls back to Chat for plan execution; clearing Embeddings turns off Insight semantic search until you assign one.

## Suggested starting point

A practical baseline is one chat-capable model for both **Chat** and **Build**, a dedicated small embedding model for **Embeddings**, and an optional separate image-capable model for **Image Understanding** if you index screenshots or other images. Connections you already see in the app (for example OpenRouter or a local Ollama endpoint) work the same way: add the connection, register models with the right capabilities, then assign them under Active Models.