ENVOY / FORWARD VELOCITY
Envoy is an MCP server embedded inside your .toe that gives your AI assistant direct access to the live session — operators, parameters, connections, pixel output. It doesn't describe what a network might look like. It builds the one you asked for. Say what you want. Watch it build.
THE DIFFERENCE
Your AI assistant can suggest what to build — but without a connection to the live session, it can't see your network, read your parameters, or act on what's running. Envoy changes that in one toggle.
capture_top returns real pixel output as an imageCAPABILITIES
Every aspect of a TouchDesigner session — operators, parameters, connections, scripts, layout, performance, visual output — exposed as MCP tools the AI can call directly.
Create, delete, copy, rename, query. create_op takes any TD type string. find_children searches by name, type, depth, tags, or text content.
read_tdn returns an entire subtree — operators, parameters, connections, DAT content — in one compacted call. 20–90× fewer tokens than walking the same network via get_op + query_network, with a 5× floor verified in CI. Default omission, type_defaults, and par_templates do the compression. Use it for structural reads; fall back to get_parameter, get_op_errors, or get_dat_content when you need live runtime values.
get_parameter returns the full context — value, mode, expression, range, menu entries, default. set_parameter writes any mode in a single call.
Wire operators together, disconnect inputs, and inspect the full connection graph — including COMP parent/child connectors.
Read and write text DATs (scripts, configs) and table DATs (structured data). Edit extension code in place without leaving the session.
get_network_layout returns all operator positions in one call. New operators extend existing rows — no overlaps, no guessing.
Create, read, and modify network boxes and comment annotations. The AI groups and labels operators the same way a human would.
get_project_performance returns FPS, frame time, GPU temp, and a hotspot ranking of the most expensive COMPs. Bottlenecks surface without you pointing at them.
execute_python runs arbitrary Python in TD's main thread. The escape hatch for anything that needs looping, branching, or full TD access between steps.
Inspect the live TD Python API — classes, methods, properties — and call operator methods by name. The AI looks up the API while using it.
Tag operators, query externalization status, force-save to disk — the full Embody lifecycle as MCP tools. Build something, externalize it, without switching focus.
get_td_status, launch_td, restart_td, switch_instance — run on the local bridge, available even when TD is not running.
batch_operations combines any set of tool calls into one round-trip. Position 10 operators, connect them, set their parameters — one request, not 30.
VISUAL FEEDBACK
Every other tool in Envoy works with structure — operators, parameters, connections. capture_top works with what's actually rendering. It captures a TOP's output as an image and returns it directly in the response. The AI sees the pixels — not your description of them.
This is the feedback loop that was always missing. The AI builds a compositing chain, captures the output at each stage, examines what it produced, and iterates — without you narrating the screen.
Eyes. The AI doesn't just build your network. It sees what it built.
ARCHITECTURE
Every tool call follows the same safe path from your AI client into the live TD session and back.
Your AI client sends a tool call. A local bridge script forwards it to Envoy's server on localhost — nothing leaves your machine.
The request is validated and queued for TD's main thread. Envoy never touches a TD object directly — it waits for the safe window.
TouchDesigner picks up the operation on its own thread, with full access to every operator, parameter, and connection in your project.
The response returns to your AI client with recent log entries attached — cook errors, warnings, status messages. Full context, every time.
RELIABILITY
Envoy lives inside your .toe. It starts with your project, stops when you stop it, and never exposes your session to the network. Every design decision treats that trust as load-bearing.
The MCP server never touches a TD object. All operator access runs on TD's main thread, enforced by architecture — not convention.
If Envoy goes down, it restarts itself — exponential backoff, up to three attempts. Port changes trigger a clean restart automatically.
The server binds to 127.0.0.1. It's not reachable from the network. Your session stays on your machine.
Every operation has a hard 30-second timeout. Long-running tasks fail cleanly rather than blocking TD or freezing the bridge.
Every response piggybacks recent log entries — cook errors, warnings, extension messages. The AI never loses context between calls.
ZERO SETUP
When Envoy starts for the first time, it writes a complete AI client configuration to your git repo root — or project folder if there's no git. Every file your AI client needs is generated and kept in sync.
/run-tests, /status, /explore-network
.toe / .tox and externalized file tracking
Regenerate at any time: op.Embody.InitEnvoy() for MCP + AI config, op.Embody.InitGit() for git config.
THE WORKFLOW
Envoy is the forward layer — it gives the AI access to build. It works with the other two layers to close the full loop.
lateral velocity.
The AI builds something via Envoy, then externalizes it using Embody's MCP tools. The work is immediately tracked, version-controlled, and restorable on next open.
the substrate.
Envoy reads the live network via export_network to see what's on screen. It modifies the JSON and imports it back — changes appear instantly, and the diff is human-readable.
the record.
Every build session ends in a commit. The agent reads git diff at session start, understands what changed, and continues where it left off — without you summarizing anything.
Forward velocity. You describe. The AI builds, externalizes, and reads the diff next session. The distance between idea and network is the time it takes to say a sentence.
DOCUMENTATION
Enable Envoy, connect your AI client, and verify the session is live.
Every tool, every parameter, every return value. The complete catalog.
The dual-thread model, bridge design, instance management, and recovery paths.
Auto-generated config — rules, skills, slash commands, and how they work together.