Updating & Uninstalling

​

Updating

mibyan update

​

Bundled desktop updates

This build doesn’t get updates. Ask the developer who gave it to you for a new build.

​

Source channels and install identity

mibyan update --install-id
mibyan update --set-channel stable
mibyan update --channel stable --check
# Or track published canary commits in this source installation:
mibyan update --set-channel canary
mibyan update

​

Passive update notices

mibyan config set updates.check false

​

What happens during an update

1. Pre-update snapshot — Mibyan saves selected state files for every profile in that profile’s state-snapshots/ directory. These include pairing data, cron jobs, config.yaml, .env, and auth.json. Automatic quick snapshots skip individual files larger than 1 GiB. updates.pre_update_backup selects quick, full, or off. Full archives use the backup exclusions. Recovery uses Snapshots and rollback. Quick snapshots recover state files, not application code. The snapshot is best-effort: if it fails, the update prints a ⚠ Pre-update snapshot FAILED warning and continues, and the receipt records pre_update_backup as a failed step (a deliberate off/--no-backup lands in the receipt’s skips with its reason instead).
2. Code update — applies the configured source branch or stable release tag and updates submodules.
3. Post-pull syntax validation + auto-rollback — after the pull, Mibyan compiles the nine critical files every mibyan invocation imports at startup. If any fails to parse (e.g. an orphan merge-conflict marker, an accidentally truncated file), Mibyan rolls the install back so your shell stays bootable: it resets the checkout to the commit it ran before the pull (git reset --hard <pre-pull-sha>), or, when the update switched away from a detached checkout or a parked feature branch, returns there with git checkout --detach <sha> / git checkout <branch> (a branch it cannot check out again is restored detached at the same commit). Re-run mibyan update once the upstream fix lands.
4. Dependency preparation — PM provisions required tools and prepares a complete Python environment from the new lock, existing extras, and enabled plugin requirements. It validates that environment before publishing its selection. A plugin never fails the update. A plugin that no longer fits the new core is added to plugins.disabled in every profile that enables it (a memory provider has memory.provider cleared). That covers a requires-python that excludes Mibyan’s Python, a manifest_version newer than this Mibyan supports, and dependencies that the resolver proves can’t resolve alongside core and earlier plugins in config order, or that fail their own build. A download or network failure gets one retry and is disabled if it fails again. The update prints ⚠ Disabled plugin '<name>' in <home>: <reason>, records it in the receipt’s warnings, and continues. Re-enable it with mibyan plugins enable <name> once the plugin ships a compatible release, or once the network is back. A requires_mibyan range the running version misses never disables a plugin, because a source checkout without release tags can read as an older release. That plugin sits out instead (⚠ Left plugin '<name>' … out of this update), stays enabled, and rejoins once Mibyan reports a version it accepts. A secondary profile whose config cannot be read sits out the same way until the config is fixed. Only a core that cannot build on its own fails this step.
5. Config migration — detects new config options added since your version and prompts you to set them
6. Desktop rebuild (stage-and-swap) — if the Mibyan Desktop app was built from this checkout, it is rebuilt so the GUI matches the new code. The rebuild packs into a temporary staging directory next to apps/desktop/release/, verifies the staged app, and only then renames it over the previous build (on Windows a real-time scanner briefly holding release/win-unpacked is ridden out with a few short retries). A rebuild that fails at any point — corrupt Electron download, missing dependency, disk full — leaves the previous app untouched and launchable; the update fails at that step, and mibyan desktop --build-only --force-build or the next mibyan update retries the rebuild. On macOS the rebuilt bundle is then copied (with ditto, signature intact) over a stale /Applications/Mibyan.app or ~/Applications/Mibyan.app, so the copy Finder and the Dock launch matches the backend; an installed copy that is currently running is left alone and the update tells you to quit it and run mibyan update again. If a copy an earlier update installed has since been removed (including dragged to the Trash), the update rebuilds it if needed, puts it back and says so, so Finder, the Dock and Spotlight find Mibyan again; mibyan uninstall removes the app for good. On Windows, when the update finishes from inside the Desktop app it would rebuild (the app completing an interrupted update at launch), the rebuild is skipped with a notice instead: Windows locks a running app’s files, and stopping the app would end the update with it. The rest of the update completes; quit Mibyan Desktop and run mibyan desktop from a terminal, or use Update now in Settings → About, to rebuild and reopen it.
7. Gateway auto-restart: running gateways are refreshed after the update completes. Service-managed gateways (systemd on Linux, launchd on macOS) restart through the service manager. Manual gateways are relaunched when Mibyan can map their PID to a profile. Manually launched mibyan serve / mibyan dashboard backends are different: the updater leaves them running and asks their owner to restart them. See Manual backend restart reminders. Backends owned by a running Desktop app remain the app’s responsibility.
8. Multiplex migration (multi-profile installs) — once the fleet is verified on the new code, an install with two or more profiles that still run one gateway per profile is folded into a single multiplexed default gateway when nothing blocks it (same as mibyan gateway migrate --multiplex --yes); if a blocker exists (a bot token shared by two profiles, a secondary profile binding a port with no /p/<profile>/ ingress) the update prints the blockers with their fixes and changes nothing. Single-profile installs are never touched. See Migrating from per-profile gateways.

​

Why the gateway restart can take a while

  → mibyan-gateway: draining (up to 1875s)...
  ⏳ still draining — 1560s left before the forced restart
     waiting on 1 active work unit(s):
       • cron job 6ba19dab68df (nightly-scout) in external worker pid 573597, running 6m40s
     finish or kill the work above to release the drain now; agent.restart_after_turn_timeout in config.yaml caps this wait

​

Missing Windows updater files

​

Fetch fails with should_include_obj should only be called on existing objects

# macOS / Linux
repo="${mibyan_HOME:-$HOME/.mibyan}/mibyan-agent"
for p in "$repo"/.git/objects/pack/pack-*.pack; do [ -e "${p%.pack}.promisor" ] || : > "${p%.pack}.promisor"; done

# Windows
$repo = Join-Path ($(if ($env:mibyan_HOME) { $env:mibyan_HOME } else { "$env:LOCALAPPDATA\mibyan" })) 'mibyan-agent'
Get-ChildItem "$repo\.git\objects\pack\pack-*.pack" | ForEach-Object {
  $m = [IO.Path]::ChangeExtension($_.FullName, '.promisor')
  if (-not (Test-Path -LiteralPath $m)) { New-Item -ItemType File -Path $m | Out-Null }
}

git -C "$repo" rev-list --objects --missing=print --all | grep '^?' | cut -c2- | git -C "$repo" fetch -q --no-tags --stdin origin
git -C "$repo" rev-list --objects --missing=error --all >/dev/null && echo complete

git -C $repo rev-list --objects --missing=print --all | Where-Object { $_.StartsWith('?') } | ForEach-Object { $_.Substring(1) } | git -C $repo fetch -q --no-tags --stdin origin
git -C $repo rev-list --objects --missing=error --all | Out-Null; $LASTEXITCODE   # 0 = complete

​

Updating against a non-default branch: --branch

mibyan update --branch release-candidate
mibyan update --check --branch experimental   # preview behindness only

​

Checkout parked on a feature branch

• Branch fully merged (every commit already contained in origin/main — git cherry reports nothing unmerged): the update says so — Checkout was parked on '<branch>' (fully merged) — switched back to main — and stays on main afterwards.
• Branch has unmerged commits but the tree is clean: the update still switches to main so the update can proceed — this is what non-interactive callers (the desktop update button, gateway /update, cron) rely on, since they have no way to resolve a skip. Your commits are untouched: git checkout never discards committed work, and the update prints a loud notice naming the branch and commit count, plus the git checkout <branch> command to pick the work back up later.

​

Local commits on the target branch

​

Local changes on non-interactive updates

# ~/.mibyan/config.yaml
updates:
  non_interactive_local_changes: stash   # default: keep + auto-restore
  # non_interactive_local_changes: discard  # throw local source edits away

• stash (default) — auto-stash, pull, then auto-restore your changes on top of the updated code. Nothing is lost; if a restore hits conflicts they’re preserved in a git stash for manual recovery.
• discard — auto-stash and drop the stash after the pull, so the update always lands on a clean tree. Use this only on machines where you never intend to keep local edits to the Mibyan source. It stash-drops (not git reset --hard + git clean -fd), so ignored paths like node_modules, venv, and build outputs are never touched.

cd ~/.mibyan/mibyan-agent   # or your install root
git stash list --format='%gd %H %s'   # find the mibyan-update-autostash entry
git stash apply stash@{0}

​

Preview-only: mibyan update --check

​

Fleet preview: mibyan update --plan

​

Update receipts and the fleet version check

​

Manual backend restart reminders

​

Automated updates from inside the gateway: --no-gateway-restart

​

Interrupted gateway restarts

​

Full pre-update backup: --backup

mibyan update --backup

# ~/.mibyan/config.yaml
updates:
  pre_update_backup: full

• quick saves the selected state files described above. This is the default.
• full adds a zip archive with the backup exclusions. Large data directories can take several minutes.
• off disables pre-update backups. --no-backup selects this mode for one run.

​

Windows process ownership and dependency changes

​

Recommended Post-Update Validation

1. git status --short — if the tree is unexpectedly dirty, inspect before continuing
2. mibyan doctor — checks config, dependencies, and service health
3. mibyan --version — confirm the version bumped as expected
4. If you use the gateway: mibyan gateway status
5. mibyan pm status — inspect dependency preparation and any failed steps.

​

If your terminal disconnects mid-update

• The update ignores SIGHUP, so closing your SSH session or terminal window no longer kills it mid-install. pip and git child processes inherit this protection, so the Python environment cannot be left half-installed by a dropped connection.
• All output is mirrored to ~/.mibyan/logs/update.log while the update runs. If your terminal disappears, reconnect and inspect the log to see whether the update finished and whether the gateway restart succeeded:

tail -f ~/.mibyan/logs/update.log

• Ctrl-C (SIGINT) and system shutdown (SIGTERM) are still honored — those are deliberate cancellations, not accidents.

​

Checking your current version

mibyan --version

​

Updating from Messaging Platforms

/update

​

Manual source maintenance and rollback

​

Python 3.14 and older interpreters

• pip install ., uv pip install ., pip install -e ., or a Homebrew/PyPI package built on Python 3.11–3.13 installs mibyan-agent with no dependencies and the package does not import. These install methods are unsupported; use the source installer or a packaged build.
• A Nix build outside the repo flake sees the same marker-gated dependency set and needs a 3.14 interpreter.
• A mibyan launcher that still points at a pre-migration venv should be repaired with mibyan update (or python -m pm.cli install from the checkout), not by reinstalling into the old venv.

​

Image-managed installs (Docker): the provenance marker

​

Note for Nix users

# Update the flake input
nix flake update mibyan-agent

# Or rebuild with the latest
nix profile upgrade mibyan-agent

nix profile rollback

​

Uninstalling

mibyan uninstall

​

Manual Uninstall

rm -f ~/.local/bin/mibyan
rm -rf /path/to/mibyan-agent
rm -rf ~/.mibyan            # Optional — keep if you plan to reinstall

mibyan gateway stop
# Linux: systemctl --user disable mibyan-gateway
# macOS: launchctl remove ai.mibyan.gateway