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