Updating & Uninstalling

Updating

Update to the latest version with a single command:

noora update

This pulls the latest code from main, updates dependencies, and prompts you to configure any new options that were added since your last update.

tip

noora update automatically detects new configuration options and prompts you to add them. If you skipped that prompt, you can manually run noora config check to see missing options, then noora config migrate to interactively add them.

What happens during an update

When you run noora update, the following steps occur:

1. Pre-update snapshot — a lightweight state snapshot is saved by default (covers pairing data, cron jobs, config.yaml, .env, auth.json, and other state files that get modified at runtime; individual files over 1 GiB are skipped so a large sessions DB never slows the update down). Controlled by updates.pre_update_backup (quick by default, full for a zip of all of NOORA_HOME, off to disable). Recoverable via the snapshot restore flow described under Snapshots and rollback.
2. Git pull — pulls the latest code from the main branch and updates submodules
3. Post-pull syntax validation + auto-rollback — after the pull, Noora compiles the nine critical files every noora invocation imports at startup. If any fails to parse (e.g. an orphan merge-conflict marker, an accidentally truncated file), Noora runs git reset --hard <pre-pull-sha> to roll the install back so your shell stays bootable. Re-run noora update once the upstream fix lands.
4. Dependency install — runs uv pip install -e ".[all]" to pick up new or changed dependencies
5. Config migration — detects new config options added since your version and prompts you to set them
6. Gateway auto-restart — running gateways are refreshed after the update completes so the new code takes effect immediately. Service-managed gateways (systemd on Linux, launchd on macOS) are restarted through the service manager. Manual gateways are relaunched automatically when Noora can map the running PID back to a profile.

Updating against a non-default branch: --branch

By default noora update tracks origin/main. Pass --branch <name> to update against a different branch — useful for QA channels, feature branches, or release-candidate testing:

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

If your local checkout is on a different branch, Noora auto-stashes any uncommitted work, switches HEAD to the target branch, and then pulls. Branches that don't exist locally are auto-tracked from origin/<name> (git checkout -B <name> origin/<name>). Branches that don't exist anywhere fail cleanly — your stashed changes are restored before exit so you're never stranded in a weird state. The main-only fork-upstream sync logic is automatically skipped on non-main branches.

Local changes on non-interactive updates

When you run noora update in a terminal, Noora stashes any uncommitted source-tree changes, pulls, then asks whether to restore them — exactly as it always has. Nothing changes for interactive updates.

When the update runs without a terminal — from the desktop/chat app's "Update" button or a gateway-triggered update — there's no prompt to answer. The updates.non_interactive_local_changes setting decides what happens to your stashed changes:

# ~/.noora/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 Noora source. It stash-drops (not git reset --hard + git clean -fd), so ignored paths like node_modules, venv, and build outputs are never touched.

In the desktop app this is Settings → Advanced → In-App Update Local Changes.

Preview-only: noora update --check

Want to know if an update is available before pulling? Run noora update --check — it fetches and compares commits against origin/main. No files are modified, no gateway is restarted. Useful in scripts and cron jobs that gate on "is there an update".

Full pre-update backup: --backup

For high-value profiles (production gateways, shared team installs) you can opt into a full pre-pull backup of NOORA_HOME (config, auth, sessions, skills, pairing):

noora update --backup

Or make it the default for every run:

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

updates.pre_update_backup is a single knob with three modes: quick (default — the lightweight state snapshot described above), full (the quick snapshot plus a complete NOORA_HOME zip; can add minutes on large homes), and off (no pre-update backup at all — --no-backup does the same for a single run). Legacy boolean values still work: true means full, false means off.

Moving to a new machine instead?

Update backups protect an in-place update. If you're migrating your whole setup to different hardware, use noora backup + noora import instead — see Exporting Noora to another machine and noora backup vs noora profile export.

Windows: another noora.exe is running

On Windows, noora update will refuse to run if it detects another noora.exe process holding the venv's entry-point executable open — most commonly the Noora Desktop app's spawned backend, an open noora REPL in another terminal, or a running gateway:

$ noora update
✗ Another noora.exe is running:
    PID 12345  noora.exe

  Updating now would fail to overwrite ...\venv\Scripts\noora.exe because
  Windows blocks REPLACE on a running executable.

  Close Noora Desktop, exit any open `noora` REPLs, and
  stop the gateway (`noora gateway stop`) before retrying.
  Override with `noora update --force` if you've already
  confirmed those processes will not write to the venv.

Close the listed processes and re-run. If you're sure the concurrent process won't interfere (rare — usually only useful when an antivirus shim is mis-attributed), pass --force to skip the check. In that case the updater will still retry the .exe rename with exponential backoff and, on stubborn locks, schedule the replacement for next reboot via MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) so the update can complete.

A second, separate guard refuses to touch the venv while any process is running from its Python interpreter (the Desktop app's backend, a gateway, a Python REPL). Those processes keep native extension files (.pyd) locked, and a dependency sync that dies partway on an access-denied error strands the install between versions. This guard is not bypassed by --force; if you're certain the detected holders are false positives, use the explicit noora update --force-venv.

Windows venv recreation is transactional

When the Windows installer must recreate an existing venv, it first moves the old directory to a unique venv.stale.* name, then creates and verifies the replacement. The old tree is deleted only after the dependency install completes and the baseline imports pass in the new tree — until then it is the rollback source (recorded in venv.pending-backup).

If the move cannot be completed, the installer stops and leaves the live venv untouched. If uv fails or reports success without creating the interpreter, any partial replacement is moved to venv.failed.* and the previous venv is restored. This keeps the health and blocker checks usable after a failed install.

A venv.stale.* or venv.failed.* directory can remain when another process still owns a file handle. Close Noora Desktop, gateways, and Python processes using the install, then retry the install/update; parked directories are cleaned up best-effort after a successful recreation.

Expected output looks like:

$ noora update
Updating Noora Agent...
📥 Pulling latest code...
Already up to date.  (or: Updating abc1234..def5678)
📦 Updating dependencies...
✅ Dependencies updated
🔍 Checking for new config options...
✅ Config is up to date  (or: Found 2 new options — running migration...)
🔄 Restarting gateways...
✅ Gateway restarted
✅ Noora Agent updated successfully!

Recommended Post-Update Validation

noora update handles the main update path, but a quick validation confirms everything landed cleanly:

1. git status --short — if the tree is unexpectedly dirty, inspect before continuing
2. noora doctor — checks config, dependencies, and service health
3. noora --version — confirm the version bumped as expected
4. If you use the gateway: noora gateway status
5. If doctor reports npm audit issues: run npm audit fix in the flagged directory

Dirty working tree after update

If git status --short shows unexpected changes after noora update, stop and inspect them before continuing. This usually means local modifications were reapplied on top of the updated code, or a dependency step refreshed lockfiles.

If your terminal disconnects mid-update

noora update protects itself against accidental terminal loss:

• 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 ~/.noora/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 ~/.noora/logs/update.log

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

You no longer need to wrap noora update in screen or tmux to survive a terminal drop.

Checking your current version

noora version

Compare against the latest release at the GitHub releases page.

Updating from Messaging Platforms

You can also update directly from Telegram, Discord, Slack, WhatsApp, or Teams by sending:

/update

This pulls the latest code, updates dependencies, and restarts running gateways. The bot will briefly go offline during the restart (typically 5–15 seconds) and then resume.

Manual Update

If you installed manually (not via the quick installer):

cd /path/to/noora-agent
# Activate the venv you created during install (outside the source tree)
export VIRTUAL_ENV="$HOME/.noora/venvs/noora-dev"
export PATH="$VIRTUAL_ENV/bin:$PATH"

# Pull latest code
git pull origin main

# Reinstall (picks up new dependencies)
uv pip install -e ".[all]"

# Check for new config options
noora config check
noora config migrate   # Interactively add any missing options

Rollback instructions

If an update introduces a problem, you can roll back to a previous version:

cd /path/to/noora-agent

# List recent versions
git log --oneline -10

# Roll back to a specific commit
git checkout <commit-hash>
uv pip install -e ".[all]"

# Restart the gateway if running
noora gateway restart

To roll back to a specific release tag (substitute your previous tag — e.g. a recent release like v2026.5.16, or any earlier tag from git tag --sort=-version:refname):

git checkout vX.Y.Z
uv pip install -e ".[all]"

warning

Rolling back may cause config incompatibilities if new options were added. Run noora config check after rolling back and remove any unrecognized options from config.yaml if you encounter errors.

Note for Nix users

Nix is no longer an explicitly supported install path (best-effort only) — see Nix Setup. If you installed via Nix flake, updates are managed through the Nix package manager:

# Update the flake input
nix flake update noora-agent

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

Nix installations are immutable — rollback is handled by Nix's generation system:

nix profile rollback

See Nix Setup for more details.

---

Uninstalling

noora uninstall

The uninstaller gives you the option to keep your configuration files (~/.noora/) for a future reinstall.

Moving to a new machine rather than leaving?

Take your setup with you before removing anything: noora backup captures the entire ~/.noora directory including credentials, while noora profile export packs a single profile with credentials excluded by design (so an export alone is not a full backup). See noora backup vs noora profile export.

Manual Uninstall

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

info

If you installed the gateway as a system service, stop and disable it first:

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