Skip to main content
Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see Install and update.
A source checkout and a packaged app are separate installations. A bundled app continues to use its own payload; it does not adopt a nearby checkout. Use a source-built desktop when you want the GUI to run modified code. User data normally lives outside the application: mibyan_HOME and the selected profile can override these defaults. Record the actual source and destination homes before changing installations.

​
1. Back up and stop the old runtime

From the existing installation, run:
Keep the backup outside any directory you plan to remove. Backups can contain credentials, so protect them accordingly. Quit the desktop and stop gateways/services that you own before the handoff. Desktop quit and mibyan gateway stop are different operations: quitting the app does not necessarily stop an independently managed messaging gateway. The per-profile gateway lock prevents duplicate gateways. Session locks and SQLite concurrency are separate concerns; starting a second process does not itself switch SQLite journal mode. For the handoff, avoid mixed code versions writing the same home while either version performs migrations.

​
2. Clone an independent checkout

For development, clone your fork instead and add the canonical repository as upstream. Select the branch or commit before preparing dependencies. Do not clone into a signed app package or overwrite the packaged runtime.

​
3. Prepare the source runtime

Read the developer workflow for native build prerequisites and current bootstrap limitations. Select your intended mibyan_HOME before preparation, then activate. Activation runs the bootstrap itself:
On native Windows, use PowerShell:
The bootstrap reads tool pins from pm/lock.json and delegates installation to PM. Current first-party code runs on Python 3.14. The wider >=3.11,<3.15 package metadata only lets older installs run the updater before PM switches them to 3.14; it is not a runtime support range. The source default is the all extra, not the desktop bundle’s --all-extras. Activation composes the installed tool environment and defines mibyan as this worktree’s CLI. The function hides an older mibyan command or MSIX alias and refuses outside the worktree. deactivate restores the shell environment and removes the function when you finish. For test dependencies and manual environments, use the development setup. See Package management for selected Python generations and writable tool storage.

​
4. Select data deliberately

For normal use on the same host, select the same mibyan_HOME and profile as the previous installation. For development, a separate home is safer because new code can migrate stored data. POSIX example:
PowerShell example:
If you change the home after preparing PM state, run the bootstrap for that home before relying on its selected dependencies. Do not assume that changing the environment variable moves data or copies runtime state. To build a source desktop, run mibyan desktop from the prepared checkout. Opening the old packaged app still starts its packaged backend.

​
Docker users

/opt/data is a container path, not necessarily a usable host path. For a bind mount, use the host-side directory as the source process’s mibyan_HOME. For a named volume or Docker Desktop VM storage, stop the old gateway first. Then export/import a backup or copy data through a controlled mount. Check ownership and permissions on the destination. A local docker build -t mibyan-agent . produces another image-managed install. It does not turn the running container into a self-updating source checkout. Recreate the container to use that image. See Docker.

​
Nix and Termux users

A local nix run . still runs a Nix-owned derivation. Its package files remain immutable and updates stay with Nix. Use nix develop for a development shell, or the source procedure above where the host supports it. The Termux distribution is a bionic APT package. The desktop/server source bootstrap is not its supported development or repair route. Use the Termux guide for its package and build boundaries.

​
Switch back without assuming a downgrade is safe

Stop the source runtime, leave its activation, and open the packaged app. Inspect which CLI command resolves before using mibyan again:
On Windows, use Get-Command mibyan -All. Do not replace an unrelated command or execution alias without checking its owner. A newer source revision can change data formats. Returning to an older package is not the reverse of a schema migration. Preserve current data and restore a compatible pre-switch backup if the older package requires it. Deleting the source checkout does not remove the packaged app. It also does not automatically collect every PM tool entry or Python generation. Use PM’s diagnostics and garbage collection rather than deleting the shared data root.

​
Troubleshooting

  • Wrong version: inspect command resolution, then use mibyan --version from the activated checkout.
  • Missing dependencies: run python -m pm.cli install from the intended source environment, then restart the affected Mibyan process.
  • Gateway already running: inspect mibyan gateway status for the selected profile. Stop the identified owner; do not kill unrelated processes.
  • Different skills after first run: newer code can sync bundled skills into the data home. A source checkout is not a read-only view of that home.