Skip to main content
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.

​
Choose an install path

Download the installer for your system from the Mibyan Desktop page.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.
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.

​
The first launch

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. The full transcript is saved to a file on disk, and its location is shown so you can attach it to a report.
On Windows an install can fail if another Mibyan command line or desktop instance is running. Stop any running Mibyan processes, then retry.
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).
1

Enter the gateway URL

Use the base URL, including https:// when it is remote. A path prefix such as /mibyan is supported.
2

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

Authenticate

Sign in with the identity provider in a browser window, or paste the session token.
4

Test, then apply

Test connection exercises the same path the app will use. When it succeeds, choose Apply and reconnect.
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.

​
Choose how Mibyan runs

After a backend is ready, onboarding asks how the agent should reach a model: 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

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

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

​
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: 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.

Next: chat and projects

Learn the composer, projects, approvals, and slash commands.