# FAQ
Short answers to common questions about Insula. Open a question to read more.
How do I set up providers / get chat working?
On first launch, **Getting Started** walks you through a provider. Later, open **Settings** from the dash (gear icon), then work under **Providers**. Use **Quick setup** for OpenRouter, Ollama, or xAI, or add a **Connection** by hand, register models, and under **Active Models** assign at least a **Chat** model.
Full setup and the other roles (Build, Embeddings, Image) are covered in [Models](/wiki/04-models).
Why isn’t Insight / semantic search working?
Insight needs an **Embeddings** model under **Settings → Active Models**. Without one, the project is not indexed and agents cannot search by meaning.
Also check the model’s **vector length** (dimensions) on the provider connection: it must match what the model returns. For example, `nomic-embed-text` requires **768** dimensions; many others use **1536**. Wrong dimensions break indexing and search.
Prerequisites and the Insight DB view are covered in [Insight DB](/wiki/07-insight-db). Vector length setup is on [Models](/wiki/04-models).
I changed my embeddings model — why is search weird?
After you change the **Embeddings** model or its **vector length** (dimensions), re-index each project that uses Insight so the index matches the new model and dimension size. Open **Insight DB** from the dash and use **Re-sync against embedding provider**.
For example, switching to `nomic-embed-text` means setting vector length to **768**, then re-syncing. See [Models](/wiki/04-models) and [Insight DB](/wiki/07-insight-db).
Do I need an Insula account?
No. Local projects and remote SSH sessions work without an account. Sign-in unlocks [Insula Network](/wiki/10-insula-network), Insula web search, account-scoped macros, and optional cloud backup of providers and app preferences.
A free account is limited to **two active devices**, **5** mesh processes, and **20** searches per 30 days. Higher caps need a paid plan. See [Subscriptions](/wiki/09-subscriptions) and [Settings spaces](/wiki/02-settings-spaces).
Where do my API keys live? Are they in the project?
Provider credentials and Active Models live in global settings on this computer (`~/.insula`), not under the project’s `.insula` folder. Keep keys out of the repository.
If you enable cloud backup while signed in, providers (including API keys) can sync across machines. See [Settings spaces](/wiki/02-settings-spaces).
What is the paid plan? Why pay for Insula?
Insula is a small, independently built project. The app itself does not require a subscription: the desktop app, agents, Insight, remotes, and your own providers all work free.
A free signed-in account already includes **Insula Network** and Insula web search. Paid raises caps to **up to 10 synced devices**, **25** mesh processes, and **1000** searches per 30 days. Most people on one or two computers never need it.
Paying is also a straightforward way to support Insula Labs and ongoing development. It does not buy model tokens or host your project files. Details are on [Subscriptions](/wiki/09-subscriptions).
How do I send a file to another machine?
Sign in on both computers (free is enough). With a project open, drag files from the file tree onto a peer in the **Insula Network** strip, or open **Hub** from the dash and use **Transfer**. The receiver must have a project open (or open one when the offer arrives).
Not available during Open Remote. How-to, cancel, and limits are on [Insula Network](/wiki/10-insula-network).
Why don’t I see Insula Network / Hub on a remote?
Insula Network is a local-desktop feature. While Open Remote is attached, Hub and the file-tree strip are hidden. Disconnect the remote to transfer files between your own Insula processes again.
See [Insula Network](/wiki/10-insula-network) and [Remote servers](/wiki/08-remote-servers).
Why does search say I’m not signed in, or that I hit a limit?
Insula **search** (the agent tool for current events and facts outside the project) needs a signed-in account. A free account allows **20** searches in a 30-day window; paid allows **1000**. Usage shows on your Insula Labs dashboard.
This is separate from **Insight** (project files) and from **xAI server-side tools** when Chat or Build is an xAI model. See [Agents](/wiki/05-agents) and [Subscriptions](/wiki/09-subscriptions).
What’s the difference between Agent, Discuss, and Plan?
**Agent** is the implementer: it can edit files, run approved terminal commands, and use Insight. **Discuss** is read-only exploration. **Plan** drafts a markdown plan you review, then you choose **Build** when you want it executed.
Plan and Discuss need a project open. Details are on [Agents](/wiki/05-agents).
Why does every terminal command ask for approval?
With an empty terminal allowlist, every command the agent wants to run shows an approval card. Choose **Always allow** to add a prefix, or edit the list under **Settings → Agent → Terminal Allowlist** (prefix or regex).
See [Agents](/wiki/05-agents).
Why can’t I use Plan/Discuss or the file tree at home?
Without a project open, Insula is in home mode: companion **Agent** chat only. There is no file tree, terminal, or Insight. Open a folder (or a known project) to unlock Plan, Discuss, and the workspace tools.
See [What is Insula](/wiki/01-what-is-insula).
Why doesn’t the language server start after I create a new project?
When you create a **new** project, language servers that are already configured (shipped defaults, or your global or project `languages.json`) do not attach until the project is reloaded.
Close the project and open it again, or otherwise reload the project workspace. After that, the language server can auto-detect the project and start.
Where language configuration lives is covered in [Settings spaces](/wiki/02-settings-spaces).
How do I connect to a remote server?
On the home dash rail, open **Remotes** (globe icon), then **Connect…**. Enter SSH details for a **Linux** host. Insula prepares the remote server component for you on first connect.
Requirements, auth options, and progress stages are on [Remote servers](/wiki/08-remote-servers).
Why can’t I open a local folder while on a remote?
One window holds either one local project or one remote session, not both. After you attach to a remote, open flows target absolute paths on that host, not a local folder picker. Use **Connect in new window…** if this window is already busy.
See [Remote servers](/wiki/08-remote-servers).
Do my providers and language servers come from this computer on remote?
Model providers and app Settings are mirrored from this computer to the remote on connect (and again on reconnect). Language and language-server configuration stay on the remote host; they are not taken from this computer while you are remote-connected.
See [Remote servers](/wiki/08-remote-servers).
I disconnected or quit — is my remote work gone?
**Disconnect remote** detaches this client; the server-side component can keep running on the host for a faster later connect. If you quit or kill the app without disconnecting, the session can go dormant on the host for on the order of a few hours, then is cleaned up.
Reconnect behavior and common failures are covered in [Remote servers](/wiki/08-remote-servers).