Envoy

embody.tools·Documentation·Manifesto·Changelog

Envoy—forward velocity.An embeddedMCPserver letsClaude Code,Codex,OpenCode,Gemini,Cursor,Windsurf, andGitHub Copilot(via VS Code) talk directly to your live TouchDesigner session. Create operators, wire them up, set parameters, write extensions, debug errors — by saying what you want. No copy-pasting code. No describing your network in chat. Idea → operators in seconds.

Embody—lateral velocity.Tag any operator and Embodyexternalizes itto files on disk that mirror your network hierarchy. Try a new direction, branch off a good one, restore the state from yesterday — all in seconds. Your externalized files are the source of truth, so every project opens already in flow.

Convoy—outward velocity.Convoy-enabled Embody nodes on a trusted LAN discover, inspect, and control each other — one AI session relaying builds, test runs, saves, screenshots, and restarts to every machine in the room. A small per-user background app keeps each node reachable even while TouchDesigner is closed.Convoy guide

TDN—the substrate that makes it all possible.TouchDesigner networks exported as human-readable YAML. The format is what lets your AI agent understand what's on the screen, what lets you diff one attempt against another, and what lets a network reconstruct itself from text on the next project open. TDN is what makes the rest of this possible.

Requirements:TouchDesigner2025.33070 or later(Windows / macOS). No Python setup needed — Embody builds a per-project Python environment (.venv) matched to TouchDesigner's own interpreter, andyour own packages can live in it too. No special folder structure either: Embody works in any project folder, and if you happen to use git, every change is also a clean diff for free.

Downloadthe Embody.toxfrom/releaseand drag it into your TouchDesigner project. TheSetup Wizardopens and walks you through the choices that matter — how much autonomy Embody gets, what to externalize, whether to enable the AI assistant (Envoy) and for which tool, permissions, whether to join a trusted-LAN Convoy, and where config files live. Nothing changes until the final click, and you can re-run it anytime via theSetup Wizardpulse on the Embody COMP.

Updating Embody:Embody updates itself — pulseCheck for Updateon the About page (or setAuto-Updateto check at startup), and a verified release is downloaded, backed up against, and swapped in place. Your settings and tracked externalizations live on disk and survive the update untouched. See theauto-update guide. Manual alternative: delete the old Embody COMP and drag the new.toxin its place — the new version picks up your on-disk state automatically, no re-scan, no files rewritten.
- Tag operators— hover any COMP or DAT and presslctrltwice to open the tagger (pick a strategy for a COMP, a file format for a DAT)
- Work normally— pressctrl + shift + uto update all externalizations, orctrl + alt + uto update only the current COMP. Externalized files are written on save; on open, the.toestays authoritative by default (Export-on-Save), while Roundtrip mode also reconstructs TDN-strategy COMPs from disk

For supported formats, folder configuration, duplicate handling, Manager UI, and more — see theEmbody docs.

Embody includesEnvoy, an embeddedMCPserver that gives AI coding assistants direct access to your live TouchDesigner session.
- Pick an AI assistant in theSetup Wizard— it opens on first install, or re-run it anytime (theSetup Wizardpulse on the Embody COMP). Prefer parameters? TogglingEnvoy Enable(Envoyenable) does the same thing with your current settings
- Server startson127.0.0.1:9870(configurable viaEnvoyport; if the port is taken by another instance, Envoy scans forward automatically)
- Auto-configuration— Envoy writes a.mcp.json(STDIO bridge, so tools are available even before TD is running) at your AI project root. By default that's the git repo root; the wizard's config-location step — or theAiprojectrootparameter — can point it at the.toefolder or a custom path instead. Projects without a git repo still get config generated in the.toefolder
- Connect— open a Claude Code session (or restart your IDE) at that root — it picks up.mcp.jsonautomatically

{ "mcpServers": { "envoy": { "type": "http", "url": "http://127.0.0.1:9870/mcp" } } }

...and 56 more. See thefull tools reference.

When Envoy starts, it always generates anAGENTS.mdfile in your project root with TD development patterns and project-specific guidance. It also writes a client-specific config for whichever assistant you select in theAiclientparameter (CLAUDE.md+.claude/for Claude Code,opencode.json+.claude/for OpenCode, Cursor/Windsurf rules, Copilot instructions,GEMINI.mdfor Gemini; Codex and OpenCode readAGENTS.mddirectly). For OpenCode and local-model setups, see theLocal Models & Open Clientsguide.

See thefull TDN specificationfor format details, import process, and round-trip guarantees.

These are the defaults — every shortcut is editable on the Embody COMP'sShortcutsparameter page (type a combo, or pulseRecordand press the keys; empty disables it). SeeKeyboard Shortcuts.

my-project/ ← project folder (optionally a git repo) ├── my-project.toe ← your TouchDesigner project ├── base1/ ← externalized operators │ ├── base2.tox ← COMP (TOX strategy) │ ├── base3.tdn ← COMP (TDN strategy — diffable YAML) │ └── text1.py ← DAT └── ...

op.Embody.Log('Something happened', 'INFO') op.Embody.Warn('Check this out') op.Embody.Error('Something broke')

op.unit_tests.RunTests() # All tests (non-blocking) op.unit_tests.RunTests(suite_name='test_path_utils') # Single suite op.unit_tests.RunTestsSync() # All in one frame (blocks TD)

Via Envoy MCP: use therun_teststool. See thefull testing docsfor coverage details and how to write new tests.

See thefull changelogfor detailed version history.

- 6.0.260:Module-level venv imports survive a cold open-- Embody authors TouchDesigner's pre-cook venv context (TDPyEnvManagerContext.yamlbeside the.toe), so.venvis onsys.pathbefore any COMP cooks and an extension that constructs before Embody can stillimportits packages (foreign contexts are never touched, deleting the file opts out, uninstall reverses it, and the wizard's footprint step discloses it); self-update validation no longer flushes dirty toxes to disk (dirty state is runtime-only now); Convoy's "Allow TD Python" gate no longer flips off on save (deviation-based reconcile replaces the voided projection flag).
- 6.0.259:Fleet Convoy triage: remote launch fixed everywhere, ghost rows self-clean, names can't mask machines-- registration claimedsys.executable(TouchDesigner's bundledpython.exe), so the host app's process probe refused every launch profileruntime_unverifiableand no node anywhere was remotely launchable (registration now claims the probed process image, and the heartbeat audit spam that came with it -- ~5,700 lines/day/node -- logs on transitions only); short-lived ghost rows retire after an hour of silence instead of 30 days; foreign name stamps heal regardless of project name and the node list prefixes the live hostname whenever a name omits it; enabling Convoy showsInstalling...instead of holdingDisabled, and Last Seen readsNeverinstead ofUnavailable.
- 6.0.257:Supervisor-managed fleets are first-class-- the Convoy host app installs from supervisor-launched TouchDesigner (an inherited stdin killed every spawn withWinError 50before any interpreter ran; children now get an explicit NUL stdin, and a genuine OS refusal reports session/Job forensics), nodes re-register deterministically at every project open (lazy extension construction left supervisor-relaunched nodesDisableduntil someone opened the Convoy page), a repo that deliberately ignores.embody/project.jsonkeeps that choice (pergit check-ignore, with a logged warning that the realm id is now per-machine), fleets update Embody remotely withupdate_embody/convoy_update_embody(sha256-pinned manifest, downgrade/build-floor refusals, no TD Python grant), and the per-project.venvbecomes a public, documented Python environment (embody_pyenv, extras, in-TDsys.pathwiring).
- 6.0.254:A deployed .toe showed the authoring machine's hostname as its Convoy Node Name-- the automatichostname / toe-stemfill persists as a constant inside the .toe and travels with it; a baked stamp whose host half is another machine but whose project half matches this project now heals to the local hostname on open, while deliberate names are never touched (Embody-written exports were already scrubbed -- the project file itself was the carrier).
- 6.0.253:A saved project could be told to "save the project first"-- the save gate asked whether a file existed atproject.folder / project.name, but TouchDesigner reportsproject.nameas the NEXT name in an incremental series (Control.35.toeon disk,project.nameControl.36.toe), so the lookup failed on projects that had been saved for months and Enable Convoy refused. Saved-ness now comes from the NAME -- TD'sNewProject[.N].toeplaceholder means never saved, anything else means saved -- with Convoy's gate and the wizard's save step delegating to that single authority, and the real.toeresolved from the increment series where a file is genuinely needed.
- 6.0.252:A fresh macOS install hit two invisible walls-- the Envoy venv build died decoding pip's output (GUI-launched macOS TD defaults to US-ASCII; every TD-side subprocess read is now forced UTF-8 and the pip/uv bootstrap runs withPYTHONPATH-class variables scrubbed, so the "Python 64-bit Module Path" preference can't contaminate the venv), and the collection "Embody it" copy flow never prompted because v6.0.251 shipped the dev machine'sClipboardautopastetoggle baked Off -- it now rests at its default in every export, persists per-user via config.json, and the fresh-install smoke asserts it. The embody.tools copy buttons are also Safari-safe now (ClipboardItem created inside the click gesture).
- 6.0.251:Worker-siderun()is now caught at write time-- Derivative confirmed that calling TD's globalrun()from a worker thread silently corrupts TD state (it does not raise), so Envoy statically lintsexecute_pythonand DAT writes and rides aTHREADING WARNINGback on the response; the full codebase audit came back clean, Envoy's own worker threads stopped printing to the Textport, Convoy's sibling API enforces its main-thread contract, and the shipped rules teach the corrected failure model plus the masked-crash diagnosis recipe.
- 6.0.250:The Convoy App no longer opens an empty terminal window at every Windows logon-- uv wrote console-subsystempythonw.exelaunchers into the daemon's venv (astral-sh/uv#19226, fixed upstream in uv 0.12.4); the installer now reads the PE subsystem instead of trusting the filename, repairs existing installs in place on their next update or Repair Convoy App, and gates release runtime bundles on the same check.
- 6.0.249:One update produced three dialogs in five seconds, and every one was wrong--Convoynodes<N>are the parameters of a runtime sequence sized toyourConvoy mesh, but the release manifest captured the developer's own component, so it declaredtheirnode count as what the build ships and the updater destroyed the surplus, calling four cells of a live status readout "settings that no longer exist". A message box is modal to its script and not to TouchDesigner, so the retired-settings dialog raised five statements before the crash sentinel cleared let the startup sweep offer to roll back an update seconds from succeeding -- and "Keep Current State" deleted the sentinel out from under the verifier, leaving the old version stamped and the component pointed into.embody/updates. The exporter no longer declares runtime blocks, the updater refuses to destroy a sequence block whatever a manifest claims, every mutation completes before anything can block, and the sentinel records its owning process so a reloaded component knows its own update is still finishing. TheConvoy App now repairs itselfinstead of logging "the payload it runs may be stale. Pulse Repair Convoy App" to a textport nobody reads: the install waits for the daemon's version to converge, performs the restart itself if it does not, and rests a surviving mismatch onStatusasNeeds repair .... Also: a developer'sShowbuiltinparstoggle had been shippingOnin released builds, presenting TouchDesigner's built-in parameter pages to every download. Verified by making a virgin install perform a real self-update with eight live node blocks against a manifest declaring none. Also: a Pulse parameter caught mid-fire had been serializingvalue: trueinto committed exports twice over, so a loaded file could re-fire it -- the exporter no longer writes a value for momentary styles.
- 6.0.246:v6.0.245 fixed one parameter where the whole category was broken-- the status readout needs BOTHnodeviewandopviewer, and assertingopvieweralone leaves it greyed out and inert, so that release still presented as a no-op. The set is no longer hand-picked: a correct install carries 25 built-in parameters set away from their TD defaults, the exporter records all of them in the release manifest, and the updater asserts whatever the build declares -- so a parameter added in a future version is carried automatically. This also closes a quieter case of the same bug:extobjectare built-in parameters, so a build that ADDED an extension would have installed it and never loaded it. Modes travel with values (w/hship bound; assigning.valwould silently flatten them to constants). The tests now assert the outcome rather than the assumption that shipped broken.
- 6.0.245:An update could install a new feature and never let it appear-- the in-place reload preserves every live parameter value, which is what keeps your settings across an update, but it preservedbuild-ownedparameters too.opviewerarrived with the status readout in v6.0.233, so every user updating from an older build got the new status viz installed and never displayed: the node kept showing the old manager panel while the About page read the new version, and the update looked like it had not run (field-reported on a v6.0.152 -> v6.0.244 update). Build-owned built-ins are now re-asserted from the new build, and only when the build actually ships what they point at. The same value-preserving reload also stranded settings that newer builds had retired, so the release manifest now declares the parameters a build ships and the updater removes anything absent from it -- telling you exactly which settings went away. A custom parameter's value is still never rewritten by an update; nine tests pin the whole contract.
- 6.0.244:v6.0.243's own regressions, found by putting an adversarial review panel on it-- the chunked dirty sweep ran a full table scanper chunk(undoing part of its own win), died permanently and silently if any one COMP's fingerprint raised, restarted from zero on every Refresh so clicking through the manager could stop it finishing, and kept running after TDN was switched off. A save could also log SUCCESS and return true with no tracking row. Plus a latent bug that predates 243: duplicate-row cleanup grouped ontype(the OP type, identical on both rows) instead ofstrategy, so a COMP externalized as both.toxand.tdnhad one of its tracking rows silently deleted on every Refresh. Shipssmallerthan 243 -- the keep-most-recent rule is one helper instead of two, position cells merge into the save's existing row write, and a dead branch is gone -- with a new suite covering the deferred sweep, the row writer, and duplicate-row semantics.
- 6.0.243:The command-prompt flash is gone, and the save that caused it is ~4x faster-- TouchDesigner is a GUI process with no console, so everysubprocesscall from inside it made Windows allocate and destroy a real console window; the manager's orange "uncommitted" badge asksgit statuson every Refresh, so every save flashed anemptyblack window (the output already went through a pipe). All nine remaining TD-side spawn sites now passCREATE_NO_WINDOW, guarded by a new suite that fails on any future spawn without it. Profiling the save then found ~99% of anemptyCOMP save was bookkeeping: the stale-file scan rglob'd the whole project folder before filtering to one subtree (~150-200ms -> a few ms; whole-project exports unchanged), duplicate-row cleanup re-scanned every row once per path (504.7ms -> 6.9ms), the strategy lookup ran a full table scan per COMP (82.8ms -> 18.3ms), and the duplicate-path check probed the TD tag store once per known tag per operator where one read suffices. The whole-project TDN fingerprint sweep, 255ms in one frame, is now chunked across frames. Empty TDN save 306ms -> 95ms; Refresh 724ms -> 44.5ms.
- 6.0.241:Two field-reported TDN bugs, both live-reproduced before a line was written-- an individual "Reload tdn" left nested externalized children as empty shells whose stale fingerprints let the next auto-export overwrite the child's good.tdnwith an empty network (import now restores every nested shell from its own file in the same pass, and automatic exports refuse to overwrite a non-empty file from an empty COMP); and a wire on input 2 of a fixed-connector operator exported at position 0 and reimported onto input 0 -- the exporter now enumerates real connectors, producing the sparse null arrays the spec always documented, with the same fix applied to Envoy'sget_op/get_connectionsso agents finally see true connector indices.
- 6.0.240:The realm recovery gets its missing direction-- v239's Resolve could only KEEP this machine's realm, but the field case is a machine whose own realm is the wrong one; "Join <!-- -->" adopts a live-announced realm through a sequence that never passes through an unbound instant, refuses un-evidenced ids, shows reverse-DNS hostnames for the machines asking to be joined, and rebinds the current project in the same confirmed click. Field-validated end to end on a two-machine LAN.
- 6.0.239:The split-realm bug, root-caused and closed-- a single UDP broadcast from any un-admitted host on the subnet could permanently wedge a daemon intolocal_realm_conflict; committed realms now move only on an admitted peer's evidence, foreign registrations refuse without poisoning state, the genesis listen window is randomized as designed, every realm transition audits its source, andResolve Realm Conflict...gives the wedge an exit it never had.
- 6.0.237:The first session tells the truth-- a fresh install watched Envoy turn red in the middle of its one-time dependency install (the wedge dwell is per-operation now), "Check and Notify" never checked until the second session (the fresh-install path schedules the startup check), and a Ctrl+S left the "Saved" counter claiming hours-old work (the post-save hook stamps it).
- 6.0.235:One status layout, minimal by design, and nothing on it that is not true-- three rows where the marks ARE the readout, ~65% larger text at the same panel width, a red version row only when an update is genuinely waiting or failed, and a running Convoy daemon that can no longer be reported as a failed install.
- 6.0.234:The status readout stops reporting work that is not happening, and the setup wizard stops eating your first click-- three rows (the auto-save, Convoy, and the project step behind them) fell through to a RUNNING default for states that meanfinished,stoppedornever started, so a fresh install drew a permanent busy mark and a stopped Convoy left a clock climbing beside work that was not happening; the auto-save row now answers how long ago the work reached disk, seeded at startup from the newest tracked write and measured against the calendar rather than folded into a 24-hour clock. The wizard's save card opened its modal from inside the click callback, which swallows the mouse-up and made every firstNexta no-op -- broken since v6.0.204, thirty builds; every wizard modal now waits on the real mouse-up. The startup bars view is removed in favour of one status view for the whole session (the module goes 1,691 lines -> 1,076), taking the write-only published-step record with it, and every Convoy host action now names a blocked child-process spawn instead of leaking a raw OSError.
- 6.0.233:The Embody node says what the project is doing, agent work is actually checkpointed, and a fresh install stops failing Convoy on its way in-- the node's viewer carries a live status readout that never fabricates a percentage, computed once per event rather than 60 times a second (a settled panel cooks zero times; a status change costs ~0.65 ms);execute_pythonandexec_op_method, which previously armed no auto-save checkpoint at all, now arm a coarse one; enabling Convoy waits for the Python environment Envoy is still building instead of racing it and failing; a long-lived Convoy worker no longer dies on the module teardown a save produces; a TouchDesigner that cannot spawn child processes is reported as such instead of blaming your Python; and a live Embot could still reach a.tdnthrough the asynchronous project-wide export, now closed from both walks.
- 6.0.222:A review of 219/220 found a data-loss defect in the release itself-- the reaper could delete a delivery record it had merely failed toopen(an antivirus handle, fd exhaustion, a concurrent rename), including the unacknowledgedindeterminatethat is the sole may-have-run proof. Corruption must now be proven and a proven-corrupt record is quarantined rather than deleted. Plus: everything the Convoy App writes is flushed before the rename that publishes it; two silent ways the reconcile loop could stop until TD restarted; the button's help and log line now match the contract the code enforces; and the two paths of the 219 fix that mutation testing showed were untested.
- 6.0.220:Upgrading Embody can update the Convoy App without restarting TouchDesigner-- the automatic daemon update is budgeted one attempt per TD session, and both its guards live in a session store that survives the Embody COMP being replaced. So an upgrade in a live session could never update the daemon: new Embody, old daemon, none of the fixes it was upgraded for. The budget is now keyed on the Embody version too, so an upgrade re-arms exactly one attempt without re-opening the retry loop. Live-verified: a fresh install took this machine's daemon from 6.0.212 to 6.0.220 on its own.
- 6.0.219:Duplicate node rows clear themselves-- one predicate treated "a delivery that has not finished" and "a finished result nobody collected" as the same thing, and it gated all three cleanup paths, so a single uncollected result made a duplicate row permanent (a field machine had 11 rows and 123 job records, 115 of them exactly that class). A finished result no longer pins a row anywhere; a queued delivery on a superseded identity is durably refused rather than left to haunt it; work past the dispatch boundary is never touched. Forget Offline Nodes stops logging a refusal as a success, names the nodes it kept and the deliveries pinning them, and restores a declined row in the same frame. Two latent ghost-resurrection paths (commit-before-write on both delete paths) closed, and an unreadable job record no longer freezes cleanup forever.
- 6.0.217:Forget Offline Nodes clears the blocks in the same frame-- the confirmed rows leave the sequence synchronously with the click, with no daemon round trip in the visual path; the daemon apply runs behind it purely as reconciliation.
- 6.0.216:The forget redraw is real-- a confirmed forget supersedes the already-armed reconcile tick (which captures its delay when it schedules) and arms a fresh one two frames out.
- 6.0.215:Forget Offline Nodes pulls its redraw forward-- a confirmed forget marks the register due and drops the tick to its minimum instead of waiting out the 30-60 s heartbeat.
- 6.0.214:Manager container alignment fix-- the manager UI's container justifies its children to the top.
- 6.0.213:The Convoy App updates itself-- the daemon reports the version of the code it actually runs, an older one is updated in place the moment a newer Embody registers with it (installs verify the daemon they restarted), and the last two duplicate-row ghost classes are gone: a Save-As into a new folder retires the old row, and a reclaimed port's stale claim is cleared.
- 6.0.212:Readable dialogs-- every message box wraps its prose to ~70 characters per line through one central choke point (structure and file paths preserved), and Forget Offline Nodes shows a visible all-clear instead of a silent log line when there is nothing to forget.
- 6.0.211:One project, one row-- a live session's versioned save no longer leaves a ghost duplicate in the Convoy node list (the old row held a port that belonged to its own successor and read as "live" forever); plus the newForget Offline Nodes...button, which names every row in a confirmation before removing this machine's offline entries.
- 6.0.210:op.Convoy-- the convoy COMP carries a global OP shortcut, so scripts and docs address it asop.Convoy.ext.ConvoyExt...instead of a path chain; contract-test pinned.
- 6.0.209:Repair Convoy App works over a running daemon(and the Host App buttons are renamed Convoy App) -- macOS bootstrapped onto the still-loaded LaunchAgent label (launchctl EIO 5), so repairing a healthy host app always failed; the installer now gracefully stops the old daemon, boots the label out, waits for launchd to drop it, then bootstraps. Windows gets the same graceful stop (the old process silently kept running old code). Also: the "no usable interpreter" warning fires once instead of three times, and never on an unsaved project.
- 6.0.208:Convoy stale nodes clear themselves-- the host app's retention sweep forgets nodes whose.toewas deleted (after ~30 min of silence) and nodes unseen for 30 days, never touching merely-offline or busy nodes (an unplugged drive is never read as a deletion); the newconvoy_forget_nodetool wires the daemon's existing recovery route for immediate manual cleanup.
- 6.0.207:A fresh install writes nothing to disk before the project is saved-- thelogs/folder,.embody/catalog, externalizations table, and project state files all deferred behind the wizard's save gate instead of landing orphaned in TouchDesigner's default folder (file logging resumes on the first post-save line; the catalog flushes post-save; additions self-heal on the first sweep). Also: Convoy node names stop baking the unsavedNewProject.1placeholder -- the Node Name fill waits for a saved project and heals already-baked placeholders in place.
- 6.0.206:Wizard save button un-wedged-- the save step's option group was never registered with the wizard's central click router, so on a fresh project the "Save the project now" card ignored every click and the wizard was stuck; the group is wired, the action card fires once per click (a canceled dialog no longer reopens), and a routing contract test pins every group to the router pattern.
- 6.0.205:Wizard footer pinned-- 6.0.204's self-sizing descriptions outgrew the fixed panel on the three tallest steps, clipping Back/Next off the bottom; the panel is now sized to the tallest step and a fill spacer pins the footer to the same bottom position on every page, with a new contract test that recomputes every step's stack fromwizard.tdnge

…