Auto-Update¶

Embody can check GitHub for new releases and update itself in place — no manual download, no drag-and-drop, and no loss of your settings or externalizations.

Running a Convoy fleet? Nodes take the same update remotely -- update_embody / convoy_update_embody, no per-machine visit and no TD Python grant. See Fleet Updates.

An update never writes your content: the post-update validation reconciles Embody's tracking without saving dirty externalizations -- anything you had unsaved stays exactly as unsaved as it was, flagged in the manager for you to save when you choose.

Availability

Self-update ships with Embody v6.0.143+. Older installs update manually one last time (drag in the new release .tox as before); from then on the updater is available.

Quick start¶

Check now: pulse Check for Update (About page). If a newer release exists you'll see the version pair and a link to its release notes, and can install with one click.
Automatic: set Auto-Update (About page) to Check and Notify or Check and Install. It defaults to Off — nothing is checked and nothing leaves your machine until you opt in.

Parameters (About page)¶

Parameter	Name	Meaning
Auto-Update	`Autoupdate`	A fresh install ships set to `Check and Notify` (the parameter's own default is `Off`, but the released `.tox` carries `Check and Notify`, so a new install does check once at startup until you change it). `Off`: never checks. `Check and Notify`: checks once at startup and shows availability in Update Status — nothing is installed. `Check and Install`: checks at startup and installs a verified update automatically. A check that can't complete (no network, no manifest, TD too old) is logged quietly; a failure during an install (backup, reload, verify, rollback) always shows a dialog.
Check for Update	`Checkforupdate`	Checks GitHub now and prompts if an update is available (`up to date` and network errors are reported in a dialog).
Update Status	`Updatestatus`	Read-only status line: `Disabled` (Auto-Update is Off -- the fresh-install resting state), `Up to date (v6.0.150)`, `v6.0.151 available`, `Downloading...`, `Retrying download (2/3)...`, `Updated to v6.0.151`, or an error summary.

The Autoupdate choice is a persisted setting (.embody/config.json), so it survives updates, project moves, and re-installs like every other Embody preference.

What an update does¶

Check — a background request to api.github.com/repos/dylanroscover/Embody/releases/latest. The frame loop is never blocked. On a manual check every outcome is shown in a dialog; on the automatic startup path a failed check is logged and shown in Update Status without interrupting you.
Gate — the release's embody-release.json manifest is fetched and validated. If the release requires a newer TouchDesigner build than the one running (min_td_build), the update is refused with a clear message before anything is downloaded — a .tox saved in a newer TD build fails to load in older ones.
Download — the release .tox is downloaded to .embody/updates/ and verified against the manifest's byte size and SHA-256 digest. A download that fails verification is discarded.
Back up — the currently installed Embody is exported to .embody/updates/backup-v<version>.tox and sanity-checked. On the manual path you are offered a project save first — the saved .toe is the recovery point of last resort.
Install (in place) — Embody's contents are reloaded from the new .tox using TouchDesigner's external-tox mechanism. The Embody COMP itself is never destroyed: its network location, wires, global op.Embody shortcut, and your parameter values all survive. New parameters introduced by the update appear with their defaults. Envoy is stopped cleanly first and restarts through its normal startup path afterward (if you had it enabled).
Verify — after the new version boots, the updater confirms the component is intact, stamps the new version metadata, reconciles parameters, detaches from the downloaded file, clears the in-flight sentinel, and only then reports success — one dialog for the whole update, which also names any settings the new version retired. If verification fails, the pre-update backup is restored automatically and the failure is reported.

The reporting deliberately comes last. A message box is modal to the script that raised it but not to TouchDesigner, whose scheduled callbacks keep running behind it — so a dialog raised mid-verification used to park the update half-applied, with its crash sentinel still on disk, long enough for the startup sweep to find it and offer to roll back an update that was seconds from succeeding.

Your externalized files and the externalizations table are untouched by design — the table lives beside Embody precisely so it survives component replacement, and the new version revalidates every tracked operator on boot (the same path a manual drag-in upgrade uses).

Safety model¶

Nothing silent is destructive. Off is the default; Check and Notify never installs. On Check and Install, failures during an install — anything that touches the live component (backup, reload, verify, rollback) — always raise a dialog; only a fully successful install is quiet. Failures before an install starts (a check that can't reach GitHub, an unverifiable release, a too-old TouchDesigner) are logged to the Embody log and shown in Update Status, without a startup dialog on every launch. On the manual Check for Update button, every outcome — up-to-date, unavailable, or error — is shown in a dialog.
Integrity: the manifest's SHA-256 must match the downloaded bytes, and the manifest names a bare .tox asset (no path escapes). Releases without a manifest (all releases before v6.0.143) are refused with a pointer to manual update. Note this is tamper-detection within GitHub's trust domain: the manifest and the .tox are published together, so the SHA-256 protects against a corrupted or post-publish-mutated asset, not against a compromise of the release itself. Because there is no independent signature, Check and Install is an explicit opt-in — if you are cautious, prefer Check and Notify and review each release before installing. (A signed-manifest scheme with a pinned public key is planned.)
Compatibility: min_td_build is enforced before download. Without this gate, loading a newer-build .tox on an older TouchDesigner fails silently and could leave a broken component.
Downgrade protection: version tags are compared numerically (MAJOR.MINOR.PATCH); a release whose tag is not strictly newer than the installed version is never installed. Tags that don't parse are refused.
Crash recovery: before the reload, a sentinel file (.embody/updates/pending.json) records the update in flight. If TouchDesigner crashes or is closed mid-update, the next project open detects it and offers to restore the backup. It offers that only for an update that really was interrupted: the sentinel records the process that wrote it, and an in-place reload keeps the same TouchDesigner process, so the rebuilt component recognises its own update still finishing instead of mistaking it for wreckage. If a swap is found live but nothing is left to finish it — the interrupted case where the component was already re-pointed at the new .tox — verification is re-armed rather than prompting, so the install completes instead of stalling half-applied.
Rollback: a failed verification automatically reloads the pre-update backup. If even the rollback fails, the updater tells you to close without saving and reopen — the saved .toe still holds the previous working state.
Undo: the swap is excluded from the undo stack. A stray Ctrl+Z cannot half-resurrect the old version.

When the network stalls¶

Nothing about an update can leave the updater stuck:

Every phase has a wall-clock deadline. The download owns its own budget, so a connection that trickles bytes forever (a proxy or captive portal that half-opens the socket) is abandoned instead of hanging -- a socket timeout alone would never fire on one.
A failed check or download retries itself, up to three attempts. The Update Status line shows Retrying download (2/3)... while it does.
After three failures it stops and tells you, in a dialog on the manual path (quietly in the log and Update Status on the automatic startup path), and cancels the attempt: no leftover state, no "already in progress" refusal. Press Check for Update again whenever you want.
A stalled attempt never owns the updater. If an update phase somehow stops reporting, the next attempt clears it and proceeds rather than refusing.

The dev checkout refuses self-update¶

If Embody's own source DATs are file-synced (you are working in the git repository, where the repo — not a downloaded .tox — is the source of truth), every update path refuses with a message to update via git pull instead. This protects the working tree from being clobbered.

Privacy¶

A version check is a single HTTPS request to GitHub's public API. It carries no account data or project information — GitHub sees what any web request shows it (your IP address and a user-agent naming the updater). With Auto-Update Off, Embody never phones home at all (set it yourself -- a fresh install ships on Check and Notify). Note GitHub's anonymous API allows 60 requests per hour per IP address — many machines behind one NAT (a classroom) may see checks fail temporarily; checks fail soft and never block startup.

For maintainers: the release manifest¶

Every project.save() in the dev project exports the release .tox and writes release/embody-release.json beside it:

{
 "schema": 1,
 "name": "Embody",
 "version": "6.0.143",
 "tag": "v6.0.143",
 "asset": "Embody-v6.0.143.tox",
 "size": 699178,
 "sha256": "…64 hex chars…",
 "td_build": "2025.33070",
 "min_td_build": "2025.33070",
 "build": 842,
 "date": "2026-07-21",
 "exported_at": "2026-07-21T12:00:00+00:00"
}

min_td_build is the build the .tox was saved with — the support floor by construction. The GitHub release step attaches every file in release/, so the manifest rides along automatically. A release without its manifest is invisible to the updater — users on auto-update simply won't receive it.

Troubleshooting¶

Symptom	Cause / fix
"cannot be verified: release has no embody-release.json"	The release predates the manifest system. Update manually from GitHub.
"requires TouchDesigner build X+"	Your TD build is older than the release's floor. Update TouchDesigner, or stay on the current Embody.
"Update failed after 3 tries -- check your internet connection"	The check or download failed three times in a row (no internet, a proxy that stalls the transfer, GitHub down, or the 60/hour anonymous rate limit shared per IP). The attempt is cancelled and nothing is left half-done -- press Check for Update again whenever you like.
"An update is already running (download)"	A check or download really is in flight. It retries by itself and stops on its own; you never have to restart TouchDesigner to get out of it.
"A previous update to vX did not complete" on a manual check	An earlier update stopped before it could be verified. Choose `Restore Backup` to go back to the pre-update version, or `Discard and Continue` to drop the leftover and check again.
"Update Recovery" dialog at startup	A previous update was interrupted. `Restore Backup` returns to the pre-update version; `Keep Current State` leaves things as they are. It never appears for an update that is merely still finishing — if you see it, the update really did stop.
"N settings no longer exist in this version and were removed"	The new version retired those parameters; their values are gone with them. It arrives inside the update's own success dialog, never as a separate alarm, and it never names Convoy node rows or any other runtime-populated sequence — those are a live readout, not settings, and an update leaves them alone.
Status shows an old version after update	The verify step stamps version metadata a few seconds after the reload; if it still shows stale info, check the Embody log for a rollback report.
Updater refuses in the dev repo	Intended — see above. Use `git pull`.