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

# Install and update Mibyan Desktop

> Install paths, the one-time first-launch install, connecting to an existing gateway, updates, and app versus backend version skew

This page covers getting Mibyan Desktop onto your computer, what happens on the first launch, and how updates work. If something goes wrong, see [Troubleshooting](/products/desktop-guide/troubleshooting).

## Choose an install path

<Tabs>
  <Tab title="Prebuilt installer" icon="download">
    Download the installer for your system from the Mibyan Desktop page.

    | System | Formats |
    | - | - |
    | macOS 12 or later | Universal DMG and zip (Apple silicon and Intel) |
    | Windows | NSIS installer and MSI |
    | Linux | AppImage, `.deb`, and `.rpm` |

    The installer sets up what the app needs, including Python 3.11 or later, a portable Git, and ripgrep. On Windows the portable Git is unpacked inside your user profile and does not touch any Git you already have.

    <Note>
      The public Mac release opens through an early-access list. Join it on the Mibyan Desktop page and you are told when the first public release is ready.
    </Note>
  </Tab>

  <Tab title="From the Mibyan CLI" icon="terminal">
    If you already have the Mibyan command line, run:

    ```bash theme={null}
    mibyan desktop
    ```

    This builds and launches the app against your existing install, with the same configuration, keys, sessions, and skills. Nothing is copied or migrated.
  </Tab>

  <Tab title="Connect to a gateway you run" icon="network-wired">
    You can skip the local install entirely and point the app at a Mibyan gateway you already run. See [Connect to an existing Mibyan](#connect-to-an-existing-mibyan) below and [Connections and profiles](/products/desktop-guide/connections-and-profiles).
  </Tab>
</Tabs>

## The first launch

```mermaid theme={null}
flowchart TD
  A["Launch"] --> B["Sign in to your Mibyan account"]
  B --> C{"Usable runtime or saved remote connection?"}
  C -- "Yes" --> H["Start Mibyan"]
  C -- "No" --> D["Set up Mibyan Desktop"]
  D --> E["Connect to existing Mibyan"]
  D --> F["Install Mibyan locally"]
  E --> G["Test connection, apply, reconnect"]
  F --> I["One-time install, stage by stage"]
  G --> H
  I --> H
  H --> J["Choose how Mibyan runs and a default model"]
```

The boot screen shows plain-language steps while it works: starting Mibyan Desktop, starting the desktop connection, connecting the live desktop gateway, loading settings, and loading recent chats. If the backend is remote and slow to answer, it says it is reconnecting to the remote backend.

### One-time local install

Choosing **Install Mibyan locally** downloads Mibyan, creates its Python environment, and runs the backend on this computer. It is a one-time step; later launches skip it.

Each stage shows one of five states: **Pending**, **Installing**, **Done**, **Skipped**, or **Failed**. The screen shows how many steps are complete, which stage is running now, and lets you expand the installer output.

| Control | What it does |
| - | - |
| Show installer output | Reveals the live output and its line count |
| Copy output | Copies the output to send to support |
| Cancel install | Stops the install |
| Reload and retry | Try again after a failure |

The full transcript is saved to a file on disk, and its location is shown so you can attach it to a report.

<Warning>
  On Windows an install can fail if another Mibyan command line or desktop instance is running. Stop any running Mibyan processes, then retry.
</Warning>

If automated first-launch install is not available on your operating system yet, the app shows the exact install command to run in a terminal, where it will install, and a **retry** button for after you have run it. Copy the command with **Copy command**, or open **View install docs**.

### Connect to an existing Mibyan

Use this when a gateway already runs elsewhere (a server, a home lab, a work machine).

<Steps>
  <Step title="Enter the gateway URL">
    Use the base URL, including `https://` when it is remote. A path prefix such as `/mibyan` is supported.
  </Step>

  <Step title="Let the app detect authentication">
    Desktop checks whether the gateway needs a **session token** or **browser sign-in**. Hosted gateways use OAuth or a username and password. Self-hosted ones may use a session token from the gateway's `.env` file.
  </Step>

  <Step title="Authenticate">
    Sign in with the identity provider in a browser window, or paste the session token.
  </Step>

  <Step title="Test, then apply">
    **Test connection** exercises the same path the app will use. When it succeeds, choose **Apply and reconnect**.
  </Step>
</Steps>

<Info>
  A one-time sign-in credential is never reused. Each connection asks for a fresh one, and only a confirmed rejection from the gateway triggers a new sign-in. A timeout or network problem is treated as a connectivity problem, not a sign-in problem.
</Info>

### Choose how Mibyan runs

After a backend is ready, onboarding asks how the agent should reach a model:

| Option | What it means |
| - | - |
| **Mibyan account** | Runs through the Mibyan gateway on your account. Calls and usage are charged to that account. Recommended |
| **Your own provider** | Use an account or API key from a provider such as OpenRouter, OpenAI, Gemini, xAI, or Fireworks. Calls go straight to that provider and are billed by them |
| **A local model** | Point Mibyan at a server on your device, such as Ollama, LM Studio, vLLM, or llama.cpp. Choose the server, discover its models, then pick one |
| **Choose later** | Skip and configure a provider later in Settings |

Some providers sign in through your browser (you authorize Mibyan there and are connected automatically), some show a verification code to enter, and some sign in once through their own command line. Nothing needs to be copied for the first two.

The onboarding ends with **Default model** and **Begin**. You can change the model at any time.

## Keeping Mibyan up to date

Mibyan Desktop has two parts that update on their own schedules: the **desktop app** and the **backend** (the agent). Both versions appear in the status bar (`Mibyan Desktop v...` and `Backend v...`) and in **Settings, About**.

### Automatic checks

The app checks for updates in the background and shows an **Update ready** notification with the number of changes included. Turn this off in **Settings, About, Automatic updates**. Use **Check now** to look immediately.

### What an update looks like

```mermaid theme={null}
flowchart LR
  A["Getting ready"] --> B["Downloading"]
  B --> C["Almost there"]
  C --> D["Finishing up"]
  D --> E["Updating Mibyan"]
  E --> F["Rebuilding the desktop app"]
  F --> G["Restarting Mibyan"]
  G --> H["Update complete"]
```

When you choose **Update now**, the Mibyan updater takes over in its own window and reopens Mibyan automatically when it finishes. Do not reopen Mibyan yourself while it is updating. If the update does not finish, nothing is lost and you can try again.

### When an update cannot run by itself

<AccordionGroup>
  <Accordion title="You installed from the command line" icon="terminal">
    Updates run in the terminal too. The app shows the command to paste, and Mibyan picks up the new version the next time you launch it. You can also run `mibyan update` yourself.
  </Accordion>

  <Accordion title="The backend updated but the app package did not" icon="code-compare">
    This shows as **Update the desktop app**. On Linux, update or reinstall your AppImage, `.deb`, or `.rpm` to match. The same situation appears as **App build out of date** in **About** when the runtime is newer than the app, because new interface features are missing until the app updates. If updating does not clear the warning, reinstall from the latest installer.
  </Accordion>

  <Accordion title="The backend is older than the app" icon="triangle-exclamation">
    You see **Backend out of date**: the backend is older than this desktop build and may not work correctly. Choose **Update Mibyan** to align them.
  </Accordion>

  <Accordion title="A remote backend" icon="server">
    The remote backend applies the update and restarts. The app reconnects automatically when it is back. If the backend does not return, the update may not have completed, so check the backend host.
  </Accordion>

  <Accordion title="Local previews are holding ports" icon="plug-circle-xmark">
    Mibyan needs to stop local preview servers before updating. **Close previews and update** stops them without touching your files. Processes that Mibyan cannot safely close (another app, terminal, or service) must be closed by you before you try again.
  </Accordion>
</AccordionGroup>

### Update every gateway at once

In **Settings, Gateways** you can choose **Update all instances** to send an update to every registered gateway. Instances managed by Mibyan Cloud are skipped, since Mibyan updates those. Each row reports Update dispatched, Skipped, or Update failed.

## Health checks and backups

Open the Command Center (`Cmd` or `Ctrl` with `.`) and go to **Maintenance**:

| Action | What it does |
| - | - |
| **Run doctor** | Health-checks the install, config, and providers |
| **Security audit** | Scans config and skills for risky settings |
| **Create backup** | Zips config, memories, skills, and sessions |
| **Debug share** | Uploads a redacted report and logs and gives you shareable links that auto-delete after 6 hours |
| **Skill curator** | Pause, resume, or run the background review that archives stale agent-created skills |

From the terminal, `mibyan doctor` and `mibyan debug share` do the same. `mibyan debug share --local` prints the report without uploading it.

## Logs and crash reports

* **Open logs** reveals the desktop log in your file manager. It is the first thing to check when the backend does not start.
* **Settings, About, Save crash reports locally** keeps compressed crash dumps on this device. They are never uploaded automatically, and Send diagnostics includes them only if you choose.

<Card title="Next: chat and projects" icon="folder-tree" horizontal href="/products/desktop-guide/chat-and-projects">
  Learn the composer, projects, approvals, and slash commands.
</Card>