# Insula Labs — full documentation dump

# Wiki
# slug: index
# source: https://insulalabs.io/wiki/index.md

# Wiki

Welcome to the Insula product wiki. Topics are listed in the sidebar — many pages are still drafts and will fill in over time.

---

# What is Insula
# slug: 01-what-is-insula
# source: https://insulalabs.io/wiki/01-what-is-insula.md

# What is Insula

## Overview

Insula is a personal, chat-first agentic desktop editor from Insula Labs. Conversation is the default surface: you talk with a coding companion that can explore a project, answer questions, draft plans, and carry out work with the models you configure.

When a project folder is open, the same window can grow into a full workspace. Alongside chat you can browse files, edit code, run terminals, search the project by meaning through Insight, and open a simple in-app browser. Settings and account live in their own windows so the primary surface stays focused on the work.

## Who it is for

Insula is for people who want a local coding companion inside a real project workspace. You keep control of which models run, what the agent may do, and when larger changes proceed. Typical use is to open a folder, discuss the codebase, plan a change, then implement it with clear review points along the way.

## Home and projects

Without a project open, Insula is in home mode. You get Agent chat as a companion: manage known projects, open a folder, and handle account sign-in. There is no file tree, terminal, or code search in this state. Each time you land in home, a new chat session starts; past home sessions stay available from a session picker.

Open a folder (or pick a known project) and the window becomes a project workspace. Plan and Discuss modes unlock. The agent can work with project files, terminals, and Insight. Close the project and you return to home mode.

## Workspace

Insula stays chat-first even with a project open. By default you still see the conversation; a slim dash on the right opens project tools. Expand the layout to show files, editor, and chat together. The editor hosts file tabs, terminals, Insight, and the browser. Panel order and open work are remembered per project when you collapse back to chat-only.

Settings open from the top bar in a separate window. Account opens from the dash the same way.

## Modes and plans

With a project open you choose among three modes. Each mode keeps its own conversation.

- **Agent** is always available. At home it is the companion. With a project open it is the direct implementer: it can read and change files, run approved terminal commands, use Insight, and load skills.
- **Discuss** is read-only exploration and explanation. It helps you understand the project without edits or command execution.
- **Plan** drafts durable markdown plans you can watch take shape in the editor. When a plan is ready, you choose **Build**. A builder then carries out the plan while you follow progress in the plan conversation. If the planner needs a decision, it can ask you before continuing.

Agent and Discuss detail, tool behavior, and related settings belong on the Agents page. Plan authoring and Build stay short here; deeper agent mechanics live later.

## Insight

Insight is a per-project local semantic index of your project files. Agents and the Insight view can find code and other content by meaning. It needs an embeddings model assigned in Settings. Indexing respects ignore rules so bulk or private paths can stay out of the index. Changing the embeddings model means the project should be re-indexed.

Insight is local to the machine and project data store. Full ignore semantics, search behavior, and day-to-day index operations are covered on the Insight page.

## Models

You assign models by role:

- **Chat** powers ordinary Agent and Discuss turns, and plan drafting.
- **Build** powers the plan builder. If Build is unset, Chat is used for builds.
- **Embeddings** powers Insight. Without it, semantic search is unavailable.
- **Image understanding** describes images so they can contribute context (for example while indexing). It does not generate images.

Provider setup, costs, and recommended pairings are on the Models page.

## Rules, skills, and macros

Three related ideas shape how the agent behaves and how you start work:

- **Rules** are standing instructions the agent receives (project conventions, tone, constraints).
- **Skills** are on-demand playbooks the agent can load when a task matches a named procedure.
- **Macros** are quick prompt buttons on the Command Panel. They fire a stored prompt into a new agent tab.

Rules, skills, and macros can live on this computer, in the open project, or (for some macros) on your signed-in account. How spaces combine and how you author each kind is covered on the Settings spaces, Skills and rules, and Macros pages.

## Staying in control

You stay in the loop on consequential steps:

- Terminal commands the agent wants to run require approval unless you have already allowed a matching pattern.
- Plans are documents you can read as they are written. Build starts when you choose it, and a finished build is marked so it is not run again by accident.
- In Plan mode, the agent can pause with a direct question when a choice blocks progress.

Approvals, allowlists, and agent settings are detailed on the Agents page and in Settings.

## Account and remote

An **Insula account** is optional. Sign-in unlocks account-scoped macros and optional cloud backup of providers and app preferences. Project files, Insight indexes, and plans stay on the machine.

**Open Remote** lets you use another machine over the network as the workspace host while the desktop app acts as the client. Provisioning, reconnect behavior, and what loads from the remote side are on the Remote servers page.

## Next topics

- [Settings and spaces](/wiki/02-settings-spaces)
- [Skills and rules](/wiki/03-skills-and-rules)
- [Models](/wiki/04-models)
- [Agents](/wiki/05-agents)
- [Macros](/wiki/06-macros)
- [Insight](/wiki/07-insight-db)
- [Remote servers](/wiki/08-remote-servers)

---

# Settings spaces
# slug: 02-settings-spaces
# source: https://insulalabs.io/wiki/02-settings-spaces.md

# Settings spaces

Insula keeps configuration in three spaces: this computer (global `~/.insula`), the open project (`<project>/.insula`), and your signed-in account (across machines). Where something lives determines who shares it, what overrides what, and whether it follows you to another computer.

## Global (this computer)

Global settings live under `~/.insula/` (or the platform home equivalent on Windows). Open **Settings** from the top bar at any time; that window is not tied to a project.

From Settings you configure:

- Providers and Active Models (Chat, Build, Embeddings, Image)
- Theme
- Editor preferences (word wrap, minimap, line numbers, font size, tab size)
- Agent preferences (terminal allowlist, compaction)
- Insight preferences (image understanding)

The same home directory also holds personal rules, skills, Global macros, and `languages.json`.

Machine-only project data (Insight index, plans, chats, kanban, notes) lives under `~/.insula/projects/...`. That data stays on this computer and is never part of the repository.

## Project (shareable)

Project settings live under `<project>/.insula/`. Opening a project does not create this directory. Add it when you want shared configuration: ask the agent to load `skill_bootstrap-insula`, or create the files yourself. Confirm before anything is written.

A project `.insula` may contain:

| Kind | Path | Purpose |
|------|------|---------|
| Rules | `rules/` | Conventions delivered to the agent for this project |
| Skills | `skills/<name>/SKILL.md` | Procedures the agent can load (`/skill_...`) |
| Macros | `macros/` | Local Command Panel macros for this project |
| Languages | `languages.json` | Optional editor language and language-server overrides |

Commit these files when the team should share them. Keep provider keys, theme, Insight indexes, kanban, notes, and plans out of project `.insula`; those belong under global home storage.

## How layers combine

| Kind | Behavior |
|------|----------|
| Rules | If the project has `rules/`, those rules fully replace global rules for that project |
| Skills | Global and project skills merge; when names match, the project skill is used |
| Languages | Shipped defaults, then global `languages.json`, then project `languages.json`; matching extension keys or server ids use the project entry |
| Macros | Global, Local, and Account are three separate sets. The Command Panel scope selects which set you edit and fire |

## Account (across machines)

Account features live in the **Account** window (dash → Account), separate from Settings.

1. **Sign in** unlocks account features through the browser login flow.
2. **Cloud backup** (signed in, then enable backup) syncs providers (including API keys and Active Models) and app preferences (theme, editor, agent, Insight). When both this computer and Insula already have providers, choose **Restore from Insula** or **Keep this computer**.
3. **Account macros** sync when you are signed in. Cloud backup does not need to be enabled. Edit them in the Command Panel under the Account scope.

These stay on the local machine: project files, Insight indexes, plans, session transcripts, Global macros, and Local macros.

On a remote connection, Settings from this computer can be pushed to the host so agents match. Project `.insula` and language configuration stay with the remote host. See [Remote servers](/wiki/08-remote-servers).

## Practical workflows

1. Personal defaults on one machine: use Settings and files under `~/.insula`.
2. Team conventions: put rules, skills, and optional Local macros or `languages.json` in `<project>/.insula` and commit them. Adding project `rules/` turns off personal global rules for that project.
3. Same setup on a second machine: sign in, enable Cloud backup for providers and app preferences, and use Account macros for portable prompts.
4. Project-only shortcuts: use Local macros in the Command Panel while a project is open.

## Related topics

- [Skills and rules](/wiki/03-skills-and-rules)
- [Models](/wiki/04-models)
- [Macros](/wiki/06-macros)
- [Insight DB](/wiki/07-insight-db)
- [Remote servers](/wiki/08-remote-servers)

---

# Skills and rules
# slug: 03-skills-and-rules
# source: https://insulalabs.io/wiki/03-skills-and-rules.md

# Skills and rules

Rules are standing guidance Insula injects into the agent automatically. Skills are named procedural guides loaded on demand, either by typing `/skill_name` in chat or when the agent selects a matching skill for the task.

Global versus project layout for `.insula` is covered in [Settings spaces](/wiki/02-settings-spaces).

## Where they live

| Kind | Global | Project |
|------|--------|---------|
| Rules | `~/.insula/rules/` | `<project>/.insula/rules/` |
| Skills | `~/.insula/skills/<dir>/SKILL.md` | `<project>/.insula/skills/<dir>/SKILL.md` |

Rules are markdown files under `rules/`, searched recursively. Insula accepts `.md` and `.mdc` extensions.

If the project has no `rules/` directory, global rules are used. If `<project>/.insula/rules/` exists, it fully replaces `~/.insula/rules/` for that project. An empty project `rules/` directory means no rules. Skills from both locations are merged; when names collide, the project skill wins.

With no project open (home), global skills remain available. Rules are not applied.

Insula seeds managed defaults into the global folders on launch when those files are missing or differ from the shipped copies. Extra files you add are left alone.

## Rules

A rule file is markdown. Optional YAML frontmatter sits between a leading pair of `---` lines; the body after the closing `---` is the guidance the agent receives.

### Frontmatter fields

These fields are honored:

| Field | Form | Effect |
|-------|------|--------|
| `description` | string | Label used when the rule is delivered. If frontmatter is present and `description` is empty, the filename is used. |
| `globs` | string, comma-separated string, or YAML array of strings | Project-relative path patterns. Supports doublestar forms such as `**`, `*`, `{}`, and `[]`. |
| `alwaysApply` | boolean | When `true`, the rule is included from the start of each agent turn while a project is open. |

Any other frontmatter keys are ignored. Do not set a non-empty `kind` field; that causes the file to be skipped entirely.

Without frontmatter, the whole file is treated as body. In that case there is no filename fallback for `description`, and the rule only participates if you later add `alwaysApply` or matching `globs`.

### When rules enter context

**Always-apply** (`alwaysApply: true`): appended at the start of Agent, Discuss, Plan, and related project turns. Keep these short: project identity, layout, and pointers.

**Path-triggered** (globs, `alwaysApply` false or omitted): when the agent first reads or writes a project-relative path that matches a glob, matching rules that have not yet been delivered in that conversation are appended once. After delivery, that rule path is not re-sent for the rest of the session.

A rule with neither `alwaysApply: true` nor a matching glob never enters context.

### Examples

Always-apply:

```markdown
---
description: "Project identity and layout"
alwaysApply: true
---

- Shared agent config lives under `.insula/`.
- Prefer existing packages over new shims.
```

Path-triggered (string or array globs):

```markdown
---
description: "Go conventions"
globs: "**/*.go"
alwaysApply: false
---

- Match surrounding package style.
- Do not edit go.mod by hand.
```

```markdown
---
description: "Docs and wiki"
globs:
  - "docs/**"
  - "**/*.md"
alwaysApply: false
---

- Keep user-facing docs free of implementation detail.
```

Comma-separated globs in one string also work: `globs: "*.go,*.md"`.

### Authoring guidance

1. Creating `<project>/.insula/rules/` replaces global rules for that project. Plan the full set you need before adding the directory.
2. Prefer small always-apply files. Put area-specific conventions behind globs so they appear when those files are touched.
3. Write short, concrete bodies that name real paths in the project.

## Skills

Each skill is a directory containing `SKILL.md`. Optional sibling folders:

- `references/`: supporting files the agent can read relative to the skill directory
- `scripts/`: non-hidden files listed for the agent to prefer via the terminal when present

Only immediate child directories of `skills/` are scanned. Nested skill trees are not discovered.

### Frontmatter

| Field | Effect |
|-------|--------|
| `name` | Slash-command and selection name. If omitted, the folder name is used. |
| `description` | Drives agent selection. If omitted, defaults to a generic placeholder. Write a specific description. |

By convention, names start with `skill_`. Other names load if present.

Example:

```markdown
---
name: skill_bootstrap-insula
description: Bootstrap a .insula directory in the open project
---

Procedural steps for the agent.
```

### Loading a skill

1. **Slash command:** type `/` in the chat composer. Autocomplete lists available skills by name and description. Including `/exact_name` in your message force-loads that skill for the turn.
2. **Agent selection:** the agent can load a skill whose description matches the task.

Skills are available in Agent (including home, with global skills only), Discuss, Plan, and related modes.

## Setup

To create or extend project `.insula` content, load the shipped skill `/skill_bootstrap-insula` and follow it. Confirm before anything is created under `.insula/`. That skill also covers languages and macros; this page covers rules and skills only.

There is no Settings panel for authoring rules or skills. Edit the files on disk.

## Practical limits

- Edits to rule files may not apply until you start a new conversation or switch projects.
- Skills are rescanned each turn. New or renamed skills appear in slash autocomplete after the skill list refreshes.
- Path-triggered rules deliver once per rule file path per conversation session.
- Rules apply only while a project is open.

---

# Models
# slug: 04-models
# source: https://insulalabs.io/wiki/04-models.md

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

---

# Agents
# slug: 05-agents
# source: https://insulalabs.io/wiki/05-agents.md

# Agents

Agents in Insula are chat tabs: **Agent**, **Discuss**, and **Plan**. Each tab keeps its own conversation. With a project open, the agent works in that workspace. At home, only the companion **Agent** is available.

## Home and project scope

Without a project open, Insula is in home mode. You get **Agent** chat as a companion: manage remembered projects, open a folder, and handle account sign-in. There is no file tree, terminal, or Insight. Each time you land in home, a new chat session starts. Past home sessions stay available from the session picker (**New chat**, then list, open, or delete).

Open a folder (or pick a known project) and chats become scoped to that project. **Plan** and **Discuss** unlock. Close the project and you return to home.

Use the tab strip above the composer to switch conversations. **+** opens **New agent tab**. Double-click a tab to rename it, drag to reorder, and close tabs you no longer need. Plan and Discuss stay disabled until a project is open.

## Agent

**Agent** is the standard implementer. It uses the **Chat** model. See [Models](/wiki/04-models).

At home it can:

- Answer questions and help you get oriented
- List and forget remembered projects (forgets Insula's stored data for that project, such as chats and indexes; your folder on disk stays)
- Start account login

With a project open it can:

- Read and edit project files
- Run terminal commands (approval-gated; see below)
- Search the project by meaning through Insight
- Load skills (type `/` for autocomplete)
- Run deeper read-only research that returns a short briefing so the main chat stays lean

Rules and skills shape how Agent behaves. See [Skills and rules](/wiki/03-skills-and-rules). Insight setup and day-to-day use are on [Insight DB](/wiki/07-insight-db).

## Discuss

**Discuss** is available only with a project open. It is read-only exploration and explanation: it can read files, use Insight, load skills, and run research. It does not edit files or run terminal commands. For changes, switch to **Agent** or **Plan**.

## Plan

**Plan** is available only with a project open. It authors a durable markdown plan you watch take shape in the editor, then you choose when to execute it.

1. Describe the work in a **Plan** tab.
2. The plan opens live as a preview in the editor.
3. Use **Show plan** in the composer when a plan path exists.
4. Review the plan, then choose **Build** on the preview. The button moves through **Building...** to **Built**. Progress streams into the Plan conversation.
5. A finished build stays **Built** so it is not run again by accident.

Plans live in machine project data, outside the repository. Drafting uses the **Chat** model. Execution uses **Build** (or Chat if Build is unset). See [Models](/wiki/04-models).

When a decision blocks planning, Plan pauses with an **Input needed** card: **Yes** / **No**, multiple choice, or free-text **Answer**. One question is pending at a time. Clearing the conversation or closing the project clears a pending question.

## Terminal commands and approvals

When Agent or a Build wants to run a shell command, Insula shows a **Command approval** card:

- **Allow** runs that command once
- **Always allow** runs it and adds a prefix (the command's first word) to the allowlist
- **Deny** blocks the command

Open **Settings** from the top bar, then **Agent**, to edit **Terminal Allowlist**. Entries are **prefix** or **regex**. With an empty allowlist, every command asks for approval.

**Agent Terminals** on the composer lists commands the agent started. Use **Kill** or **Kill all** to stop them. That list is separate from terminals you open yourself in the editor or dash.

## Compaction

Long conversations grow prompt size. Use **Compact** on the composer to summarize older turns. You may see a compacted marker in the transcript. Token pressure shows against the compaction cap.

Under **Settings → Agent → Context Compaction**, set **Compaction cap (tokens)** (default `200000`). The cap is global for agent contexts and is the threshold at which compaction is suggested.

## Related topics

- [What is Insula](/wiki/01-what-is-insula)
- [Settings spaces](/wiki/02-settings-spaces)
- [Skills and rules](/wiki/03-skills-and-rules)
- [Models](/wiki/04-models)
- [Macros](/wiki/06-macros) (a macro opens a new Agent, Plan, or Discuss tab and sends its prompt)
- [Insight DB](/wiki/07-insight-db)

---

# Macros
# slug: 06-macros
# source: https://insulalabs.io/wiki/06-macros.md

# Macros

Macros are quick prompt buttons on the Command Panel. Each configured slot stores a prompt, an icon URL, and a mode. Firing a macro opens a new Agent, Plan, or Discuss tab and sends that prompt immediately. You can include `/skill_name` mentions in the prompt body the same way you do in chat.

## Where they appear

The Command Panel lives in the editor column: below the editor and above the Terminals dock. It appears when a project is open and the editor split is shown. Without the editor column, the panel is unavailable.

The panel has two heights:

- **Collapsed** (default on first run): a strip of nine slots, the Global | Local | Account scope control, and an expand chevron.
- **Expanded**: the same strip plus a configurator for the selected slot.

## Scopes

Global, Local, and Account are three separate sets. The Command Panel scope selects which set you edit and fire. They do not merge.

| Scope | Availability | Purpose |
|-------|--------------|---------|
| **Global** | Always | Personal macros on this computer under `~/.insula/macros/` |
| **Local** | Project open | Project macros under `<project>/.insula/macros/`; commit with the repository when the team should share them |
| **Account** | Signed in | Personal macros that sync across machines. Cloud backup does not need to be enabled |

If Local is selected without a project, or Account without a sign-in, the panel falls back to Global. Closing the project while Local is selected returns you to Global.

Where these spaces fit among settings, rules, and skills is covered in [Settings spaces](/wiki/02-settings-spaces).

## Configure a slot

There are exactly nine slots. Buttons show an icon only; the prompt source name appears in the Prompt picker.

1. Click a dashed **+** slot (or expand the panel, then click an empty slot). The panel expands and the slot is ready to edit.
2. Set **Prompt**: choose **New prompt** or an existing source in that scope's library.
3. Set **Icon URL** (live preview on the slot) and **Mode** (**Agent**, **Plan**, or **Discuss**).
4. Edit the prompt body. Placeholder text reminds you to use `/` for skills.
5. Use **Run** to fire, or **Clear slot** to unconfigure the slot.

Edits save as you work. Prompt bodies live as files under that scope’s `prompts/` directory. Several slots may share one source; editing the body updates every slot that uses it. **Clear slot** removes the slot configuration; the prompt file stays in the library.

## Run a macro

| Panel state | Action | Result |
|-------------|--------|--------|
| Collapsed, filled slot | Click the slot | Fires immediately |
| Expanded, filled slot | Click the slot | Selects the slot for editing |
| Expanded | **Run**, or send from the prompt editor | Fires the selected macro |

A fire always opens a **new** tab and sends the stored prompt. It does not continue the active chat. An empty prompt is blocked with **Macro has no prompt**. **Plan** and **Discuss** require an open project; without one those modes are unavailable.

## Skills and modes

Include `/skill_name` in a macro prompt to load a skill when the new session starts. Skill authoring and naming are covered in [Skills and rules](/wiki/03-skills-and-rules).

**Mode** chooses which kind of session the fire creates:

- **Agent** for direct work
- **Plan** for durable plan drafting
- **Discuss** for read-only exploration

Mode and tool behavior for those sessions are detailed on [Agents](/wiki/05-agents). Macros do not pick a model; Active Models from Settings apply as usual. See [Models](/wiki/04-models).

## Defaults and project setup

On a fresh install, Global may seed **Discover Code Base**: explore layout, entrypoints, languages, docs, and risks, then summarize and wait for a follow-up. Existing Global macros are left alone on later updates.

For Local macros, add project `.insula` when you want shared configuration: ask the agent to load `skill_bootstrap-insula`, or create the files yourself. Confirm before anything is written. Local macros belong under `<project>/.insula/macros/`.

## Sharing and sync

1. Personal shortcuts on one machine: use **Global**.
2. Team or repository shortcuts: use **Local** under `.insula/macros` and commit them.
3. The same personal macros on another machine: sign in and use **Account**.
4. Global and Local stay on the machine. Account macros sync when you are signed in. If cloud Account macros already exist, they take precedence over the local Account cache on login.
5. **Delete my data** removes cloud Account macros. The local Account cache may remain until you clear those slots yourself.

On a remote connection, Account macros stay with the desktop client. See [Remote servers](/wiki/08-remote-servers).

## Related topics

- [What is Insula](/wiki/01-what-is-insula)
- [Settings spaces](/wiki/02-settings-spaces)
- [Skills and rules](/wiki/03-skills-and-rules)
- [Models](/wiki/04-models)
- [Agents](/wiki/05-agents)
- [Remote servers](/wiki/08-remote-servers)

---

# Insight DB
# slug: 07-insight-db
# source: https://insulalabs.io/wiki/07-insight-db.md

# Insight DB

Insight is a per-project local semantic index of the open project's files. Agents use it to find code and other content by meaning. The index stays on this computer with the app.

## Prerequisites

Assign an **Embeddings** model under **Settings → Active Models**. Without it, Insight does not index or search.

An **Image** model is optional. With one assigned, turn on **Settings → Projects → Insight DB → Image understanding** so images can be described and included in the index. Text indexing still runs if Image is unset; the status view may warn that images are unavailable.

Provider connections, capabilities, and role assignment are covered on [Models](/wiki/04-models).

## Insight DB view

With a project open, open **Insight DB** from the right-hand dash. The view shows:

| Field | Meaning |
|-------|---------|
| Status | `idle`, `syncing`, `chunking`, or `error` |
| Embedder | The embeddings model in use |
| Last sync | When the index last finished successfully |
| Files / Chunks / Size | How much of the project is in the index |
| Warning / error | Soft issues (for example images) or hard failures |

**Re-sync against embedding provider** rebuilds or refreshes the index for the open project.

Agents are the main way you discover project content through Insight. This view is for index health and manual sync.

## How agents use it

Insight is available when a project is open: **Agent**, **Discuss**, and **Plan** (including research). Home mode has no Insight.

Agents search the index by meaning to locate relevant files and passages, then continue from those hits. They can also check whether the index is ready, busy, or in error before relying on it.

Mode behavior and tools are detailed on [Agents](/wiki/05-agents).

## Chunks and conceptual mapping

Indexed files are split into **chunks**: meaning-bearing pieces that keep enough surrounding context for retrieval, including where in the file a hit came from.

Insight also builds a map of **conceptual relations** across the project. Agents use that map to move from a question to the right areas quickly.

When status shows **chunking**, that phase of indexing is in progress. **Files** and **Chunks** on the Insight DB view reflect how much of the project is currently indexed.

## Controlling what is indexed

Indexing walks the project tree and respects ignore rules so bulk or private paths stay out.

| File | Role |
|------|------|
| `.gitignore` | Patterns that exclude paths from git also exclude them from Insight, including nested `.gitignore` files with git-style scoping |
| `.insightignore` | Same pattern style as gitignore, applied only to Insight |

A path matched by either set is not ingested. Empty files are skipped until they have content.

Vendor and build trees are often already covered by `.gitignore`. Use `.insightignore` for Insight-only exclusions: generated artifacts, large assets you keep in git, or other paths that should stay out of the index.

## Where the index lives

The index is per-project machine data under `~/.insula/projects/...`, alongside plans and chats. It is not committed to the repository, not stored under project `.insula`, and not restored by cloud backup.

Cloud backup can sync Insight **preferences** (for example image understanding) with other app settings. The index itself stays on this machine. See [Settings spaces](/wiki/02-settings-spaces).

## Keeping the index current

Opening a project starts indexing. Later file changes trigger incremental updates; status may show `syncing` or `chunking` while work is in progress.

After you change the **Embeddings** model, or when Settings warns that vector length or size changed, use **Re-sync** on each project that uses Insight so the index matches the new model.

Changing the image model requires restarting the app before new image description uses the new assignment. The image-understanding toggle takes effect on the next project open or re-sync.

Forgetting a known project removes stored Insula project data, including the Insight index. Project source files on disk are left untouched.

## Related topics

- [What is Insula](/wiki/01-what-is-insula)
- [Settings spaces](/wiki/02-settings-spaces)
- [Models](/wiki/04-models)
- [Agents](/wiki/05-agents)
- [Remote servers](/wiki/08-remote-servers)

---

# Remote servers
# slug: 08-remote-servers
# source: https://insulalabs.io/wiki/08-remote-servers.md

# Remote servers

Open Remote lets the Insula desktop app on your computer act as the client while a **Linux** host holds the workspace. You connect over **SSH**. Project files, agents, terminals, Insight, and language tools run on that host. The laptop stays the window you look at and type into.

Trust is ordinary SSH credentials. An Insula account is not required to attach to a remote; account remains optional for macros, cloud backup, and related features. See [What is Insula](/wiki/01-what-is-insula).

On first connect, and again when needed later, Insula prepares a long-lived server component on the host for you. Later connects reuse a healthy server when one is already there. You do not install a stack by hand for the normal path.

## Connect

On the home dash rail, open **Remotes** (globe icon). The menu lists saved remotes by label or `user@host`, plus **Connect…**. When you have saved entries, **Manage…** is available too.

If this window already has a project open or a remote attached, further remote connects use **Connect in new window…**. One window holds either one local project or one remote session, not both, and not two remotes at once.

### Connect Remote dialog

| Field | Notes |
|-------|--------|
| **Label** | Optional display name for the saved entry |
| **User** | SSH username |
| **Host** | Required hostname or address |
| **Port** | Defaults to `22` |
| **Auth** | SSH agent / default keys (default), identity file, or password |

Actions: **Cancel**, **Save**, **Connect**. **Forget** on a saved remote removes only the laptop’s saved connection record; it does not uninstall anything on the server.

If you use password auth, enter the password when connecting. A later reconnect with password auth stops at the dialog so you can enter it again.

While a connect is in progress, the dialog title becomes **Connecting…** and shows staged progress, for example: Checking remote, Downloading server, Verifying download, Uploading server, Starting server, Syncing providers, Provisioning server, Attaching session. Reconnect flows show recovery-oriented stages. First-time work from probe through attach can take up to several minutes when a download and provision are required.

## While you are connected

The dash rail reflects connection state in plain terms:

1. **Home (no project, no remote):** **Open project** and **Remotes** (globe).
2. **Remote attached, no project yet:** the open control becomes **Open remote project**; **Disconnect remote** appears; a **green pulsing orb** shows you are connected (tooltip and accessibility name use the remote label or `user@host`).
3. **Remote and project open:** full editor chrome, as when working locally, plus the orb. Close the project and you stay attached to the remote without a project. **Disconnect remote** tears down the client attach.
4. **Globe while this window is already busy** with a project or remote: the tooltip indicates that another remote opens in a new window.

Local folder browse and remote work do not mix in the same window. After attach, recent lists and open flows target **paths on the remote host**. Opening a project asks for an **absolute directory path** on that host (for example `/home/ubuntu/myproject`), not a local OS folder picker.

Close project while remote-connected closes the project and **keeps** the remote session (the orb stays). Disconnect leaves the remote connection from this client; the server-side component can keep running on the host so a later connect can resume more quickly.

A project path already open in another Insula window on that remote is locked; the UI surfaces that clearly.

## Reconnect and session lifetime

| Situation | What you experience |
|-----------|---------------------|
| Short network interruption | Automatic reconnect attempts (a few tries with brief backoff); progress or toasts such as reconnecting, then reconnected when it succeeds |
| Reconnect succeeds | Work continues; remote-side terminals and agents are intended to still be alive on the host |
| Reconnect gives up or the session is gone | A message along the lines of remote session lost; reconnect manually via **Remotes** |
| Explicit **Disconnect** | Clean detach from this client |
| Quit or kill the app without disconnect | The session can go **dormant** on the server: work may keep running on the host for on the order of a few hours (about three hours), then is cleaned up |
| Return after a long gap | You may resume if still within dormancy; otherwise you get a fresh session |
| Version skew of the remote server piece | The connect flow may update the server on the host, then attach again |

Attempt counts and dormancy duration are how the system behaves; there is no Remote settings panel to tune them.

## What lives on the remote

**On the remote host while connected:** project files, agents, terminals, the Insight index for that work, language and language-server configuration on that machine, and project-scoped data under the remote user’s Insula data.

**Mirrored from the laptop on connect (and again on reconnect):** model providers and app Settings (theme, editor, agent-related preferences, Insight preferences). While attached, Settings edits apply on the laptop first and are mirrored to the remote. See [Settings and spaces](/wiki/02-settings-spaces) and [Models](/wiki/04-models).

**Stay on the laptop:** window management, OS dialogs, the saved remotes list, account and sign-in, and account-scoped macros. Language configuration is **not** taken from the laptop while you are remote-connected; language tools follow the remote machine.

## Requirements

- The remote host must be **Linux** for this feature.
- You need network reachability and valid SSH authentication to that host.
- First-time provision typically needs the laptop online so it can obtain the server build.

## Common problems

Plain-language failures you may see:

- Cannot reach the host
- Authentication failed (key, agent, or password)
- Host key or trust problems
- Could not prepare or start the remote server
- Need a new window because this one already has a project or remote
- Remote session lost; reconnect
- Not connected when trying to open a remote path
- Project already open elsewhere on this remote

## Related topics

- [What is Insula](/wiki/01-what-is-insula)
- [Settings and spaces](/wiki/02-settings-spaces)
- [Models](/wiki/04-models)
- [Insight](/wiki/07-insight-db)

---

# Privacy Policy
# source: https://insulalabs.io/privacy.md

# Privacy Policy

**Last updated:** August 6, 2026

This Privacy Policy describes how Insula Labs (“we,” “us,” or “our”) collects, uses, stores, and deletes information when you use our website, accounts, and the applications and related services we operate (together, the “Services”).

We design the Services to keep your data private, secure, and honestly managed. As we add apps and change how features work, we may update this policy. Our goal stays the same: protect your information and not misuse it.

## 1. Who this covers

This policy applies to:

- Our website and account systems
- Our applications and any cloud features that sync or store settings and related data for those apps
- Authentication and device features that let you sign in and use the Services across your devices

We may expand the Services over time. This policy covers those offerings as we add them, unless a specific product publishes its own notice.

## 2. Information we collect

### Account and identity

When you create or use an account, we may store:

- Email address and name
- Authentication information (for example, a hashed password, or links to third-party sign-in providers you choose to connect)
- Basic account status needed to operate the account (such as whether the account is active)

### Service and device information

To run authentication, sessions, and app connectivity, we may store:

- Device registrations associated with your account
- Session and authentication tokens as needed to keep you signed in and secure
- Limited technical information required to operate and protect the Services

### App settings and secrets

You may choose to store with us settings and secret information used by our apps. That can include:

- Application settings and preferences
- Provider credentials such as LLM or other API keys
- Related secrets you supply so our apps can act on your behalf with third-party services

This app data is **encrypted** and **isolated per user**. It is stored so it can be used by the apps we provide for you—not shared with other users.

### Data that may stay on your devices

Some information may remain only on your devices (for example, local project files, local settings copies, or other on-device state) and is not uploaded to us unless you use sync, backup, or similar features that send that data to our Services.

## 3. How we use information

We use the information described above to:

- Provide, maintain, and improve the Services
- Authenticate you and manage your account and devices
- Sync and restore your settings and related app data across your devices when you enable those features
- Protect the security and integrity of the Services, including preventing abuse and unauthorized access
- Comply with law where required

We do **not** sell your personal information.

We do **not** use your provider API keys or other secrets you store as our own credentials, and we do not inspect them for unrelated product, marketing, or training purposes. Those secrets exist so *your* apps can use *your* providers under *your* accounts.

## 4. How we protect information

We take practical steps to protect your data, including:

- Encrypting sensitive cloud-stored settings and secrets at rest
- Isolating each user’s app data from other users
- Limiting access to what is needed to operate and secure the Services

No method of storage or transmission is perfectly secure. We work to keep systems private and secure, and we treat your secrets as confidential material for running your account—not as content for us to browse or reuse.

## 5. Sharing

We do not sell your personal information.

We may share information only:

- With infrastructure providers that help us run the Services (for hosting, storage, delivery, and similar operations), under obligations consistent with this policy
- When you direct us to (for example, connecting a third-party sign-in provider)
- If required by law, legal process, or to protect the rights, safety, or security of Insula Labs, our users, or the public
- In connection with a merger, acquisition, or similar transaction, subject to appropriate protections

Third-party providers you connect with your own API keys (such as LLM providers) process requests under *their* terms and policies when your apps call them using your credentials. That usage is between you and those providers.

## 6. Retention and deletion

While your account and data exist, we keep what is needed to provide the Services.

When you delete your data or delete your account through the Services:

- We delete your cloud-held data for that account **immediately**
- There is **no retention period**
- We do **not** keep copies to review, restore, or use later

Deletion is intended to be complete and final for data we store on your behalf in the Services.

Copies of data that remain on devices you still control (local files, local caches, or app data on those machines) are not automatically removed by our cloud deletion. You may remove those locally if you wish.

## 7. Your choices

Depending on the features available in the Services, you may be able to:

- View and update account and settings information in-product
- Enable or disable sync or backup of settings and secrets
- Manage connected sign-in providers and devices
- Delete your data or account, which permanently and immediately removes your cloud-stored data as described above

## 8. Children

The Services are not directed to children under 13, and we do not knowingly collect personal information from children under 13. If you believe a child has provided us information, contact us and we will take appropriate steps to delete it.

## 9. Changes to this policy

We may update this Privacy Policy as we expand apps and services or change how data is managed. When we do, we will post the updated policy here and revise the “Last updated” date.

Material changes take effect when posted, or on a later date we specify. Continued use of the Services after an update means you accept the revised policy.

Our intent remains to handle data privately, securely, and honestly.

## 10. Contact

For privacy questions, contact Insula Labs at bosley@Insulalabs.com.

---

# Terms of Service
# source: https://insulalabs.io/terms.md

# Terms of Service

**Last updated:** August 6, 2026

These Terms of Service (“Terms”) govern your access to and use of the websites, accounts, applications, and related services operated by Insula Labs (“we,” “us,” or “our”) (together, the “Services”).

By creating an account, signing in, or otherwise using the Services, you agree to these Terms. If you do not agree, do not use the Services.

## 1. Accounts

You must provide accurate information when creating or maintaining an account and keep your credentials secure. You are responsible for activity that occurs under your account.

You may not share account credentials in a way that allows unauthorized access, or use another person’s account without permission. Notify us promptly if you believe your account has been compromised.

We may suspend or terminate accounts that violate these Terms or that pose a security or abuse risk to the Services or other users.

## 2. The Services

We provide applications and related cloud features, which may include account authentication, device connectivity, and storage or sync of settings and related data for use in our apps.

Features may change, expand, or be discontinued as we develop the Services. We do not guarantee that any particular feature will remain available indefinitely.

## 3. Your data and secrets

You may store application settings and secret information with us for use in our apps. That can include preferences and provider credentials such as LLM or other API keys.

You represent that you have the right to use any credentials, keys, or other secrets you store, and that storing and using them through the Services does not violate third-party terms or applicable law.

You remain solely responsible for:

- How your keys and credentials are used through the Services
- Usage, billing, rate limits, and compliance with third-party providers you connect
- Content and actions initiated with those providers using your credentials

Sensitive settings and secrets you store with us are encrypted and isolated per user. They exist so our apps can operate on your behalf—not so other users can access them, and not so we can use them as our own.

Our handling of personal and account data is described in our [Privacy Policy](/privacy). When you delete your data or account through the Services, cloud-held data for that account is deleted **immediately**, with **no retention**. Local copies on devices you still control may remain until you remove them.

## 4. Data loss

We are not responsible for any loss of data arising from your use of our apps or Services, including loss caused by bugs, outages, sync or backup failures, deletion (by you or otherwise), device failure, third-party providers, or any other cause.

It is your responsibility to maintain whatever records, copies, or backups you need for recovery. Do not rely on the Services as your sole copy of anything important.

## 5. Acceptable use

You agree not to:

- Use the Services for unlawful purposes
- Attempt to access, interfere with, or disrupt other users’ accounts or isolated data
- Probe, scan, or attack the Services except with our prior written permission for legitimate security research we have agreed to
- Circumvent authentication, encryption, isolation, or other security controls
- Abuse the Services in a way that harms Insula Labs, other users, or third-party providers
- Misrepresent your identity or affiliation in connection with the Services

We may investigate suspected violations and take action we reasonably consider appropriate, including suspension or termination.

## 6. Third-party services

The Services may allow you to connect to third-party providers (including LLM and other API providers) using credentials you supply. Those providers are independent of Insula Labs. Your use of them is governed by their terms and policies. We are not responsible for third-party services, outages, pricing, or how those providers process requests made with your keys.

## 7. Intellectual property

The Services, including our software, branding, and site content we provide, are owned by Insula Labs or our licensors. These Terms do not grant you ownership of the Services.

You retain your rights in data and content you provide. You grant us a limited license to host, process, and transmit that material solely as needed to operate the Services for you.

## 8. Disclaimer

THE SERVICES ARE PROVIDED “AS IS” AND “AS AVAILABLE.” TO THE MAXIMUM EXTENT PERMITTED BY LAW, INSULA LABS DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

We do not warrant that the Services will be uninterrupted, error-free, or completely secure, or that data stored in or processed by the Services will not be lost or corrupted.

## 9. Limitation of liability

TO THE MAXIMUM EXTENT PERMITTED BY LAW, INSULA LABS WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF PROFITS, DATA, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING OUT OF OR RELATED TO YOUR USE OF THE SERVICES.

TO THE MAXIMUM EXTENT PERMITTED BY LAW, OUR TOTAL LIABILITY FOR ANY CLAIM ARISING OUT OF OR RELATED TO THE SERVICES OR THESE TERMS WILL NOT EXCEED THE GREATER OF (A) THE AMOUNTS YOU PAID US FOR THE SERVICES IN THE TWELVE MONTHS BEFORE THE CLAIM, OR (B) ONE HUNDRED U.S. DOLLARS (US $100).

Some jurisdictions do not allow certain limitations; in those cases, our liability is limited to the fullest extent permitted by law.

## 10. Changes to these Terms

We may update these Terms as we expand apps and services or change how the Services work. When we do, we will post the updated Terms here and revise the “Last updated” date.

Material changes take effect when posted, or on a later date we specify. Continued use of the Services after an update means you accept the revised Terms.

Our goal remains to offer Services that treat your data privately, securely, and honestly.

## 11. Contact

For questions about these Terms, contact Insula Labs at bosley@Insulalabs.com.

---