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

# Switching to a Source Install

> Run a separate source checkout without overwriting packaged files or losing track of user data

<Info>
  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](/products/desktop-guide/install-and-update).
</Info>

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:

| Host | Default data location |
| - | - |
| Linux, macOS, WSL, Termux | `~/.mibyan/` |
| Native Windows | `%LOCALAPPDATA%\mibyan\` |
| Official Docker container | `/opt/data/`, mapped to host storage |

`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:

```bash theme={null}
mibyan backup
mibyan gateway status
```

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

```bash theme={null}
git clone https://github.com/NousResearch/hermes-agent.git
cd mibyan-agent
```

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](/desktop/reference/package-management#developer-workflow)
for native build prerequisites and current bootstrap limitations. Select your
intended `mibyan_HOME` before preparation, then activate. Activation runs the
bootstrap itself:

```bash theme={null}
source ./activate
mibyan --version
```

On native Windows, use PowerShell:

```powershell theme={null}
. .\activate.ps1
mibyan --version
```

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](/desktop/developer-guide/contributing).
See [Package management](/desktop/reference/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:

```bash theme={null}
export mibyan_HOME="$HOME/mibyan-source-data"
mibyan setup
mibyan
```

PowerShell example:

```powershell theme={null}
$env:mibyan_HOME = Join-Path $HOME 'mibyan-source-data'
mibyan setup
mibyan
```

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](/desktop/user-guide/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:

```bash theme={null}
command -v mibyan
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.