Updating & Uninstalling

Updating

Choose the update method for the installation that is running:

Installation	Update method
Managed source checkout	tutou update, or the source-built desktop's update handoff.
Windows sideload MSIX	The desktop Update control and Windows App Installer.
Microsoft Store package	Microsoft Store updates.
macOS bundled app	The desktop Update control, through electron-updater.
Docker image	Pull the chosen image and recreate the container with the same data mount.
Nix	Update the flake/profile and rebuild.
Termux APT	pkg update, then pkg upgrade tutou-agent.

tutou update does not rewrite package-owned application files. PM manages dependencies, not application distribution: tutou pm update is a maintainer pin-update command, not an alternative application updater.

For a managed source installation:

tutou update

Source installs track main, the only valid source channel. The update prepares dependencies through PM and reports configuration changes and process-restart results.

Bundled desktop updates

On Windows, the sideload app checks the registered App Installer source. Apply downloads the .appinstaller descriptor before stopping app-owned backends, opens that local file, and quits for Windows to replace the package. A detached waiter attempts automatic relaunch after the package version changes. A waiter-registration failure produces a manual-reopen warning.

On macOS, apply downloads the ZIP update and waits for Squirrel.Mac to accept the signed app before stopping backends. Only that apply flow requests install and relaunch. An ordinary quit does not install a pending download. Download or verification failures leave backends running.

Store packages use the Store instead of either sideload feed. A broken or unavailable update check must not be interpreted as "already up to date." The application and its bundled base runtime update together; user data stays outside the package. See Desktop installation.

Stable and canary desktop bundles are separate applications. Installing canary does not replace stable, including on Windows with MSIX. Each application keeps its own desktop state and updates within the channel baked into its build; changing channels means installing the other application, not changing a setting. The canary icon has a yellow background (dark yellow in dark mode), and its CLI command is tutou-canary.

One-off commit bundles are separate from both release channels and from other commit bundles. Their red icons show the short build SHA, also used in the tutou-<short-sha> CLI command. They do not check for or install updates, including through tutou update or tutou update --check. They explain:

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

Separate applications still share Tutou profiles, configuration, and sessions under the same Tutou home. Running different builds against one profile is not schema isolation: newer builds can change stored data that an older build cannot read. Back up shared data before testing. The desktop and standalone CLI warn when another live installation uses the same profile; this is advisory, not a lock. Desktop post-update notices are scoped to the application, so launching canary cannot consume stable's pending notice. The tutou:// URL scheme remains shared; the application that most recently registered it handles links.

tip

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

Passive update notices

Pinned or noninteractive installations can disable passive CLI version and banner update checks:

tutou config set updates.check false

This suppresses both cached update notices and passive update-check network requests. The default is true. Explicit tutou update --check and tutou update still work; this setting does not control the Desktop application's updater.

What happens during an update

For an admitted source checkout, tutou update runs these phases:

1. Pre-update snapshot — Tutou 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, Tutou compiles the nine critical files every tutou invocation imports at startup. If any fails to parse (e.g. an orphan merge-conflict marker, an accidentally truncated file), Tutou 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 tutou 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 Tutou's Python, a manifest_version newer than this Tutou 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 tutou plugins enable <name> once the plugin ships a compatible release, or once the network is back. A requires_tutou 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 Tutou 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 Tutou 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 tutou desktop --build-only --force-build or the next tutou update retries the rebuild. On macOS the rebuilt bundle is then copied (with ditto, signature intact) over a stale /Applications/Tutou.app or ~/Applications/Tutou.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 tutou 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 Tutou again; tutou 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 Tutou Desktop and run tutou 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 Tutou can map their PID to a profile. Manually launched tutou serve / tutou 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 tutou 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

The restart is drain-first: the running gateway refuses new turns, then waits for in-flight work (chat turns, cron jobs, API runs) to finish before exiting, capped by agent.restart_after_turn_timeout (30 minutes by default) so a long-running job is never cut off mid-run. While that wait is in progress the updater prints, every 30 seconds, what the gateway is still holding for — for example:

  → tutou-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

Chat turns show their session key, model and current tool; cron jobs show the job id, name and the process running them (an external restart-safe worker on systemd installs, otherwise the gateway itself). tutou gateway status lists the same units while the gateway is draining. To stop waiting, finish or kill the listed work, or lower agent.restart_after_turn_timeout in config.yaml (0 enters the forced drain immediately).

Wedged work does not hold the restart: a chat turn idle past agent.gateway_timeout, or a cron run older than the scheduler's in-flight allowance (max(2 × the job's interval, cron.inflight_max_minutes), 30 minutes by default), is excluded from the wait and interrupted by the restart instead.

Work that outlives the gateway does not hold the restart either: a cron run already handed to a worker in its own systemd scope (systemd-run --user --scope, the normal case on a systemd install) keeps running when the gateway stops, and its result is delivered from the durable queue by whichever gateway comes up next — so the restart proceeds instead of waiting up to the full cap. A worker that could not get its own scope (no reachable user D-Bus session, see cron.require_restart_safe_scope) stays in the gateway's cgroup and is still awaited, because the restart would kill it mid-run.

Missing Windows updater files

If the maintained updater script is missing (for example after antivirus quarantine), the legacy update forwarder fails instead of reporting a successful hand-off. Repair the installation and review the security software's quarantine report before retrying; do not disable antivirus protection. Before reporting success, the maintained updater checks the CLI import, Windows executable header, ASAR header and packaged main entry, readable renderer HTML with a local module entry, initial module files, and current build stamp. These are minimum artifact checks, not a full dependency audit or an application/backend launch test. Missing Python is reported before waiting for Desktop shutdown; dependency repair is still allowed to run as part of the update. Electron checks maintained handoff prerequisites before stopping backends when that layout is present; genuine legacy-flat updater layouts remain supported, so not every missing updater file is detected before backend shutdown.

On Windows, a Desktop reopened during packaging is stopped again immediately before the staged build is promoted. This cleanup is restricted to executables inside that checkout's Desktop release tree; unrelated installations are not stopped. A remaining lock still makes staged promotion fail rather than bypassing the rename error.

Fetch fails with should_include_obj should only be called on existing objects

Git 2.53 and newer can crash while fetching into a partial clone when some of its pack files lack a .promisor marker. That happens when a filtered fetch turned a full or shallow clone into a partial one, or when markers were lost. tutou update marks those packs and retries the fetch once, and an installer rerun marks them before it fetches. An install whose own updater predates that fix can't fetch it: rerun the installer, or mark the packs by hand (with Tutou closed) and update again.

The checkout is tutou-agent under your Tutou home (~/.tutou, or TUTOU_HOME when set; on Windows %LOCALAPPDATA%\tutou unless TUTOU_HOME is set).

# macOS / Linux
repo="${TUTOU_HOME:-$HOME/.tutou}/tutou-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:TUTOU_HOME) { $env:TUTOU_HOME } else { "$env:LOCALAPPDATA\tutou" })) 'tutou-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 }
}

The checkout stays a partial clone. Don't remove remote.origin.promisor / partialclonefilter to get past the crash: objects that only release tags or update backups reach were never downloaded, so a non-partial checkout then fails git gc with bad tree object. If you already did, fetch the missing objects and check that none are left before turning automatic cleanup back on:

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

.git keeps growing in a partial clone

The installer's checkout is a partial clone: git downloads trees and blobs on demand, and each on-demand download is written as its own small pack. tutou update and tutou update --check fold them back together with git gc --auto (git's own gc.autoPackLimit, 50 by default), so a healthy checkout pays a no-op. They also set maintenance.commit-graph.enabled, gc.writeCommitGraph and fetch.writeCommitGraph to false in that checkout, because a commit-graph write over commits the graph has not seen yet downloads every one of their trees. Leave those settings alone, and leave gc.auto at its default: gc.auto=0 stops the fold. The first fold on a checkout that has piled up thousands of packs is a full repack and can take several minutes; the update says so before it starts, and if the fold runs past 20 minutes it stops and prints the command below. To fold by hand (with Tutou closed):

git -C "$repo" -c gc.writeCommitGraph=false gc --auto

Updating against a non-default branch: --branch

Source installs track origin/main. Use --branch NAME for a one-run branch override:

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

If your local checkout is on a different branch, Tutou 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.

Checkout parked on a feature branch

If the source checkout was left sitting on a feature branch (by tooling, a worktree experiment, or a manual checkout), tutou update switches it back to the update target automatically whenever the working tree is clean:

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

If you deliberately run a custom branch (local patches maintained on top of main), set updates.parked_branch_strategy: update_in_place in config.yaml. The update then merges origin/main into your branch instead of switching away from it — the checkout never moves, your commits survive, and the running code advances. Fast-forward when possible; on divergence a true merge behind a pre-update-<stamp> safety tag, stopping cleanly (nothing changed) on conflict. tutou update --switch-branch overrides back to the switch path for one run — useful on a deep feature branch that must not accumulate update-driven merge commits.

When the parked branch has uncommitted changes (dirty tree), Tutou does not touch it. The code update is marked SKIPPED with a loud warning naming the branch, how far behind origin/main it is, and the exact commands to resolve — instead of pretending the update succeeded. The completion line always shows the actual branch and HEAD (✓ Update complete! [main @ 30fcf9580]) so drift is visible at a glance. Set updates.auto_switch_parked_branch: false in config.yaml to disable the auto-switch entirely (the skip warning still fires).

Local commits on the target branch

Commits made directly on the update target (main) stop fast-forwards once upstream moves, and the checkout cannot tell them apart from an upstream force-push, so the update resets main to origin/main. Before the reset it saves the old HEAD as refs/tutou-update-backups/diverged-main-<stamp>-<sha> and prints that ref along with how many commits leave the branch. git log origin/main..<ref> lists them; git branch <name> <ref> or git cherry-pick brings them back. Re-running the installer over an existing checkout (install.sh / install.ps1, which desktop bootstrap does) writes the same refs. Whenever tutou update writes one, it keeps the ten newest per kind and drops any older than 30 days. To carry patches across updates, keep them on a custom branch with updates.parked_branch_strategy: update_in_place instead.

Local changes on non-interactive updates

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

The autostash only ever covers source-tree changes. On a flat install — where the git checkout root is also $TUTOU_HOME (for example an install made with TUTOU_INSTALL_DIR=$TUTOU_HOME, or one created by an older installer) — the profile's runtime state (state.db and its WAL/SHM sidecars, state-snapshots/, backups/, sessions/, cron/jobs.json, the cron/*.db stores, config.yaml, auth.json, memories/, lock/pid files, …) lives inside the checkout as untracked files. Those paths are git-ignored, so the autostash never touches them and the running gateway keeps its database through the update. If you keep other untracked files in a flat install's root, move them out of the checkout or add them to .git/info/exclude; anything untracked and not ignored is swept into the autostash like a source edit.

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:

# ~/.tutou/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 Tutou 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.

Desktop updates never auto-restore. The desktop updater invokes tutou update --keep-stash: local source edits are still stashed so the update can proceed, but they are not re-applied afterward — they stay parked in git stash and the update log prints the exact git stash apply <ref> command to bring them back. This prevents local edits from silently riding along across desktop updates and breaking the freshly updated install. (non_interactive_local_changes: discard still wins if you've opted into discarding.) To restore parked changes manually:

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

You can pass --keep-stash to a terminal tutou update too if you want the same never-reapply behavior interactively.

Preview-only: tutou update --check

tutou update --check compares the checkout with origin/main without applying code, installing dependencies, or restarting gateways. The comparison can fetch Git metadata; it is not a promise of zero filesystem writes. Package-owned installs report their external update method.

Fleet preview: tutou update --plan

Before updating a machine that runs several profiles or services, run tutou update --plan. It prints the install kind, running Tutou services across profiles, their supervisors and running code versions, and the restart mechanism for each service. Manually launched tutou serve / tutou dashboard backends appear with their recorded bind endpoint, but restart is deferred to their owner; the updater does not stop or relaunch them. Image- or package-managed installs report the external update command instead. The plan is read-only and safe on a live fleet.

The same inventory is embedded in every real update's receipt (~/.tutou/logs/update_receipts/), so after an update you can compare what the updater saw against what it did.

Update receipts and the fleet version check

Every tutou update run writes a machine-readable receipt to ~/.tutou/logs/update_receipts/ (last 20 kept, latest.json always points at the most recent): the pre-update fleet plan, each step taken, anything skipped and why, the gateway restart outcome, and the final fleet version matrix. The SQLite runtime repair is one of those steps (sqlite_runtime_repair): a failed repair records the actual reason (for example the uv sync error) and the SQLite version pair, a deferred or not-applicable repair lands in the skips with its reason. After the restart phase the updater compares each live gateway's running code against the freshly updated checkout and prints a per-profile matrix — a gateway still serving pre-update code is reported loudly with the exact restart command, and the update exits non-zero so automation never treats a mixed-version fleet as healthy. Both --plan and the fleet check ask each running gateway directly over its local control socket (gateway.sock in the profile's data directory, a named pipe on Windows) when available, so version and supervisor information comes from the gateway itself; gateways from older versions are still discovered through their state files as before.

A multiplexed default gateway is one process serving several profiles, so it appears once in the matrix and vouches for every profile in its served_profiles record. The same coverage clears the "A previous tutou update pulled new code but did not restart running gateways" hint: once that gateway (or, after a manual git pull, every gateway an update restarted) runs the current code, tutou gateway restart is enough — the hint no longer waits for the next tutou update to write a fresh receipt. The same is true of the restart obligation left by an update that died before recording which gateways it owed (or by an older updater that never recorded them): once every live gateway runs the current checkout, the obligation is retired and the hint stops. On a host that runs no gateway at all (the Desktop app alone), it is retired once no profile has a gateway that went away without a clean stop and every running backend is restarted by its own supervisor or has its own reminder. That obligation is recorded once per HOST, in the cross-profile rendezvous directory ($TUTOU_GATEWAY_LOCK_DIR, else $XDG_STATE_HOME/tutou/gateway-locks) as host-update-restart.json, so every profile's CLI sees the same one: tutou -p coder update and tutou -p writer update restart the shared multiplexed gateway once between them, not once each. An obligation left behind by an older per-profile updater (fleet_restart_pending in one profile's Tutou home) is still read and cleared. An update whose pre-update plan found no gateway at all owes nothing and leaves no breadcrumb. A backend supervised by Desktop, systemd or launchd is restarted by its supervisor and never blocks this settlement; only a manual backend whose reminder could not be saved keeps the obligation open.

Manual backend restart reminders

After updating, ask the owner of each manually launched backend to relaunch tutou serve or tutou dashboard; reconnect Desktop for an SSH backend. Restarting gateways alone does not refresh these processes.

For a verified live backend, the updater saves a reminder before recording its restart as deferred. This allows the update to complete if the remaining checks pass. An unknown process identity cannot qualify for fresh deferral.

Reminders live in serve_restart_pending/ under the active Tutou home, separately from rotating update receipts. Each reminder identifies a process by PID and creation time. Startup warnings retain it while that process is alive or its liveness is unknown, and remove it only when that exact process is confirmed gone. A later update or a healthy gateway does not remove it.

If saving fails, Tutou warns and carries the unsaved obligation into later receipts for retry. Check storage permissions and free space, and restart the backend as instructed. If both reminder and receipt storage fail, durable retention cannot be guaranteed.

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

An update launched by the gateway (a cron job, the Desktop updater, any automation that is a child of the gateway process) cannot survive its own fleet restart: the gateway drains on SIGUSR1 and systemd's KillMode=mixed then kills everything left in the cgroup, updater included. tutou update --no-gateway-restart runs the full pipeline (pull, dependencies, Node workspaces, web UI, maintenance) and skips only the restart and fleet verification. The pending-restart marker is kept, so the next CLI start warns and the next normal tutou update (or tutou gateway restart) catches the fleet up. Pair it with a separate restart step, for example a timer 10–15 minutes after the update job. The receipt records the deferral; a stale fleet caused only by the deferral does not make the update partial.

Interrupted gateway restarts

If an earlier update pulled code but did not finish restarting the fleet, the next tutou update retries even when the checkout is already current. An empty process scan does not prove recovery: failed systemd units and installed launchd jobs may have no live PID. If discovery or restart fails, or a requested service cannot be verified active, the marker stays pending and the update exits nonzero. Recover the affected services with the printed commands and retry.

A failed historical receipt alone does not prove that gateways are still stale. Startup and gateway-status warnings, as well as update catch-up, check for a live successor on the current checkout for every gateway profile recorded in that receipt. A manual gateway restart can settle receipt-only advice without rewriting the historical outcome. Manual backend obligations must first transfer to their separate reminders.

A pending restart marker records its own pre-update runtime inventory and target commit. Recovery checks that inventory, never an older receipt's inventory. Settlement requires a nonempty verified current fleet, a successor at the target commit for every recorded gateway profile, and successful handling of any identified manual backend obligations. A manual backend that is still alive or whose liveness is unknown needs a saved reminder; a confirmed exited process needs no reminder. Missing gateways, unsupported runtimes, or failed reminder writes keep the marker pending.

Legacy markers without an inventory, and malformed or unsupported inventories, cannot be automatically cleared by startup or catch-up reconciliation. Restarting all visible gateways is not enough to establish what that update owed. The warning remains until a later update completes with a new marker containing its own inventory and settles successfully.

Full pre-update backup: --backup

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

tutou update --backup

Or make it the default for every run:

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

updates.pre_update_backup has three modes:

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

Legacy boolean values remain supported: true means full, and 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 tutou backup + tutou import instead — see Exporting Tutou to another machine and tutou backup vs tutou profile export.

Windows process ownership and dependency changes

Windows can hold executable and native-extension files open while processes run. PM therefore prepares dependency generations separately instead of replacing imported libraries in place. A running process keeps its current imports until it restarts.

Follow any blocker diagnostic for the specific process and installation. Do not kill every process named Python or Tutou. Source updates and MSIX package replacement have different owners and shutdown requirements.

The parser retains --force and --force-venv for Windows compatibility. They are not normal update instructions or a guarantee that an OS file lock can be bypassed. Inspect tutou update --plan, the update log, and tutou pm status before retrying a failed update.

Recommended Post-Update Validation

After a source update, run the following diagnostics. For a bundled app, use its About page and backend health instead of Git commands inside the package.

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

Dirty working tree after update

If git status --short shows unexpected changes after tutou 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

tutou 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 ~/.tutou/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 ~/.tutou/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 tutou update in screen or tmux to survive a terminal drop.

Checking your current version

tutou --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 source maintenance and rollback

Use the source-install guide for an independent development checkout. Commit or otherwise preserve local work before changing its Git revision. Stop the services you own before replacing the code that those services run.

After changing the source revision, run that revision's dependency/bootstrap procedure. PM-managed checkouts use python -m pm.cli install from the selected source environment. A bare pip install is not equivalent: it does not prepare the managed tool store or PM's runtime selection.

A code checkout alone is not a data rollback. Newer releases can migrate configuration or databases in ways older code cannot read. Use a coherent backup from before the update if an older release requires the earlier data format. Preserve the current data before attempting a restore.

Package-owned installations use their package manager's rollback or reinstall procedure. Do not run Git or pip inside a signed app or an immutable image.

Python 3.14 and older interpreters

Tutou runs only on Python 3.14. pyproject.toml still declares requires-python = ">=3.11,<3.15", but every runtime dependency carries a python_version >= '3.14' marker. The wider range exists for one reason: a source install whose venv predates the PM migration (Python 3.11–3.13) must be able to check out the new code and run tutou update once more. That update hands off to a fresh completion process, PM provisions the pinned 3.14 interpreter from pm/lock.json, builds the dependency environment on it, and repoints the launchers. After that the old interpreter is no longer used.

What this means outside tutou update:

• pip install ., uv pip install ., pip install -e ., or a Homebrew/PyPI package built on Python 3.11–3.13 installs tutou-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 tutou launcher that still points at a pre-migration venv should be repaired with tutou update (or python -m pm.cli install from the checkout), not by reinstalling into the old venv.

Image-managed installs (Docker): the provenance marker

Published Docker images bake a small read-only marker (/etc/tutou/image-provenance.json) that authoritatively identifies the filesystem as image-managed. tutou update, tutou update --check, and the dashboard's Update button all consult it before touching anything: on an image-managed install they refuse cleanly (exit code 2), print the actual update command (docker pull tutoukeji/tutou-agent:latest), and write a refused receipt so fleet tooling can see the attempt happened. The marker wins even when a source checkout is bind-mounted into the container — the refusal is based on what the running filesystem is, not what it looks like. A damaged marker still refuses (fail-closed). Nix- and apt-managed installs refuse through the same gate using the existing detection.

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 tutou-agent

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

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

nix profile rollback

See Nix Setup for more details.

---

Uninstalling

tutou uninstall

For source installs, review tutou uninstall --dry-run before removal. The default removal can preserve configuration and user data. --full also removes data. --data removes user data without deleting package-owned code. These modes are destructive; make a backup first.

For MSIX/Store, use Windows Settings → Apps → Installed apps. For macOS, quit Tutou and move its app bundle to Trash. Docker, Nix, and Termux use the same manager that installed them. Their package files are not removed by the source uninstaller. Data deletion is separate from package removal.

Moving to a new machine rather than leaving?

Run tutou backup before you remove the installation. The full archive includes credentials but excludes downloaded runtimes, dependency environments, caches, and browser profiles. Review its skipped-file report before you delete source data. tutou profile export packs one profile without credentials. See tutou backup vs tutou profile export.

Manual Uninstall

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

info

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

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