> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections and profiles

> Run the agent locally, on a remote gateway, over SSH, or on Mibyan Cloud, and keep separate profiles with their own config, skills, and persona

Mibyan Desktop is a window onto an **agent backend**, also called a **gateway**. The backend can run on this computer or somewhere else. **Profiles** are separate agent identities that live on a gateway. This page explains both.

## Four kinds of gateway

```mermaid theme={null}
flowchart LR
  APP["Mibyan Desktop<br/>this app"]
  APP --> L["Local<br/>runs on this computer"]
  APP --> R["Remote gateway<br/>HTTP(S): LAN, VPN, internet"]
  APP --> S["SSH<br/>launched over SSH and tunneled"]
  APP --> C["Mibyan Cloud<br/>a hosted agent on your account"]
```

| Kind | What it is | Good for |
| - | - | - |
| **Local** | The Mibyan runtime managed by this app. Private, on localhost, works offline. There is only ever one | Everyday use |
| **Remote gateway** | A Mibyan gateway reachable over HTTP or HTTPS, on your network, over a VPN, or on the internet | A shared server, a home lab, a work machine |
| **SSH** | A Mibyan install reached over SSH. Mibyan is started on the remote host and tunneled to the app. There is nothing to start or expose yourself | A machine you can already SSH into |
| **Mibyan Cloud** | A hosted instance discovered through your Mibyan Cloud account | An always-on agent without running a server |

A remote agent runs commands and reads files **on that machine**, not on yours. Connect only to hosts you trust.

## Manage gateways

Open **Settings, Gateways**. It lists every registered gateway, marks the one in use (**Current**), the default (**Primary**), and the one the app manages (**App-managed**).

<Steps>
  <Step title="Add a connection">
    Choose **Add connection**, pick the kind, and give it a **name**. Names must be unique and appear everywhere the gateway does, for example Homelab or Work laptop.
  </Step>

  <Step title="Test it">
    **Test** checks that the gateway is reachable. The test exercises the connection and sign-in path the app will actually use, so a pass means it works.
  </Step>

  <Step title="Use it or make it primary">
    Switch gateways from **Sessions**. **Make primary** sets which gateway the app opens on.
  </Step>
</Steps>

Good to know:

* Profiles, chats, messaging, and scheduled jobs **stay with their gateway**. Work on a gateway you switch away from keeps running.
* The setting **At startup, return to Sessions on the last-used gateway** decides where the app opens. When it is off, the app opens on the Primary gateway.
* You cannot add a second local connection, and duplicate URLs or SSH hosts are rejected with the name of the existing one.
* **Remove** takes the connection out of this app only. The instance itself is not touched, and you can add it again any time.
* **Update all instances** sends an update to every gateway that can be updated. See [Install and update](/products/desktop-guide/install-and-update).

### Set up a remote gateway

<Steps>
  <Step title="Enter the URL">
    The base URL of the gateway. Path prefixes such as `/mibyan` are supported.
  </Step>

  <Step title="Let the app detect how it signs in">
    The app asks the gateway. Hosted gateways use OAuth (for example, sign in with your identity provider) or a username and password. Self-hosted ones use a **session token**.
  </Step>

  <Step title="Sign in or paste the token">
    Sign-in opens a browser window and refreshes itself afterward. A pasted token is used for both REST and WebSocket access. Leave the field blank to keep a saved token.
  </Step>

  <Step title="Test, then save">
    **Test remote** verifies the connection. **Save and reconnect** applies it now and keeps the app open. **Save for next restart** waits.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Where is my token stored?" icon="key">
    In your operating system's secure storage (Keychain, Credential Manager, or the Linux keyring). If no secure storage exists on the machine, Mibyan asks before saving the token **unencrypted** in the app's connection settings file, where any process running as your user could read it. On Linux, install or enable GNOME Keyring or KWallet to avoid that.
  </Accordion>

  <Accordion title="Extra gateway headers" icon="shield">
    For gateways behind an access proxy such as Cloudflare Access, add headers like `CF-Access-Client-Id` and `CF-Access-Client-Secret`. They are sent with every HTTP and WebSocket request to that gateway and stored encrypted. Headers Mibyan manages itself (such as Authorization and Cookie) are ignored.
  </Accordion>

  <Accordion title="Environment overrides" icon="terminal">
    If the environment variables `MIBYAN_DESKTOP_REMOTE_URL` and `MIBYAN_DESKTOP_REMOTE_TOKEN` are set, they control the session and the app tells you. Unset them to use the saved settings.
  </Accordion>
</AccordionGroup>

### Set up SSH

SSH mode starts Mibyan on the remote host and tunnels it to this app, so nothing needs to be exposed. It needs working **key-based** SSH access, because Mibyan runs `ssh` non-interactively.

| Field | What to enter |
| - | - |
| **Host** | `user@host`, or pick a Host alias from your `~/.ssh/config` |
| **User** | Leave blank to use your `~/.ssh/config` or current user |
| **Port** | Leave blank for 22 or your `~/.ssh/config` port |
| **Identity file** | Path to the private key. Blank uses `ssh-agent` or `~/.ssh/config` |
| **Mibyan path** | Optional full path to the remote Mibyan. Blank auto-detects |

The first host key presented is **trusted and pinned**, and any later change fails closed. **Test SSH** confirms the host is reachable and Mibyan is found. **Save** applies on the next launch, and **Connect** reconnects now. Remote hosts running Linux, macOS, or Windows are supported.

Common SSH messages and what to do:

| Message | Fix |
| - | - |
| Could not reach the host | Check the host, port, and your network |
| Authentication failed | Load your key into `ssh-agent` (`ssh-add`) or set an `IdentityFile` in `~/.ssh/config` |
| Host key has changed | Confirm it is expected, then run `ssh-keygen -R <host>` and reconnect |
| Mibyan is not installed on the remote host | Install it there, or set the Mibyan path |
| Update required | Update Mibyan on the remote host first |

### Use Mibyan Cloud

<Steps>
  <Step title="Sign in once">
    Choose **Sign in to Mibyan Cloud**. There is no URL to paste.
  </Step>

  <Step title="Choose an organization">
    If your account belongs to several, pick one. Your role in it is shown.
  </Step>

  <Step title="Pick an agent and connect">
    Your agents are listed with their status. A new one shows **Provisioning** until it is ready. Choose **Connect**.
  </Step>
</Steps>

If no agent exists, create one in the Mibyan portal and refresh. Cloud agents are managed by Mibyan, so the app does not restart or update them. If a cloud agent is down, the app offers **Check Portal status** and a way to get help.

### What the status bar tells you

The status bar shows the current connection (for example `Remote: host`, `SSH: host`, or `Cloud: host`), whether the gateway is **ready**, **needs setup**, **connecting**, **offline**, or **restarting**, and both versions. Its gateway menu offers **Reconnect gateway**, the recent activity log, and your messaging platforms. If the connection drops, the app keeps trying in the background, and you can still read and draft.

## Profiles

A **profile** is an independent Mibyan environment: its own **config, skills, memory, and persona** (`SOUL.md`). Use profiles to separate work and personal, or to give different agents different jobs.

```mermaid theme={null}
flowchart TB
  G["One gateway"] --> P1["default<br/>your main agent"]
  G --> P2["coder<br/>own skills and persona"]
  G --> P3["research<br/>own config and keys"]
```

### Create and manage

| Action | Details |
| - | - |
| **New profile** | Name it with lowercase letters, digits, hyphens, and underscores, starting with a letter or digit |
| **Clone from** | Start blank, or copy the config, skills, and `SOUL.md` from another profile (for example **Clone from default**) |
| **Rename** | Renames the profile directory and any wrapper scripts. For the default profile you set a **display name** instead, and its internal ID stays `default` |
| **Delete** | Removes the profile and its directory permanently |
| **Color** | Give each profile a color, or leave it on Auto |
| **Import and export** | Move a profile between machines |
| **Copy setup** | Copies the command that recreates the profile |
| **Edit SOUL.md** | The system prompt and persona baked into the profile. Leave it blank to keep the default |

### Switch profiles

* Use the profile picker, or `Cmd`/`Ctrl` with `1` to `9` for the first nine (`Cmd`/`Ctrl` with `Alt` and a number for 10 to 18).
* `Cmd`/`Ctrl` with `D` returns to the default profile. `Cmd`/`Ctrl` with `Shift` and the square brackets steps to the next or previous one, and `Cmd`/`Ctrl` with `Shift` and `0` toggles the **all profiles** view.
* `/profile <name>` sets the profile for new chats.
* Switching does not reboot the app. The window stays put, and other profiles' chats **keep streaming in the background**.

Settings pages show which profile they apply to, so you always know whose config you are changing.

### Run one profile on a remote host

You can send a single profile to a remote machine while everything else stays local. From the profile menu choose **Connect to a remote host**, enter the address and an access token, and confirm.

* New chats in that profile run on the remote host, and it will run commands and read files **there**, not on this computer. The profile shows a **Runs on host** badge.
* This is separate from Settings, Gateways, and does not change a gateway that has the same name.
* If the host rejects the saved token, the app tells you and lets you **Enter new token**. **Remove remote connection** puts the profile back on this computer.

<Card title="Next: skills, tools, and automation" icon="bolt" horizontal href="/products/desktop-guide/skills-and-automation">
  Extend the agent with skills, MCP servers, plugins, schedules, webhooks, and messaging.
</Card>