DSH x Blender: one TCP channel that lets an AI agent drive a live Blender session

The architecture: one channel, two processes, three ports

The plugin's central claim is a single TCP channel between DeepSeek Harness and a live GUI Blender, with fifteen model tools and no MCP assembly and no CLI adapter. The point of that phrasing is that the agent does not go through a protocol adapter layer: it talks to a process that is already running in front of you.

There are three moving parts. Blender runs in GUI mode with a bundled Python addon, the DSH Blender Bridge, which listens on 127.0.0.1:9876. A Node.js backend runs the plugin and exposes its own HTTP surface on port 9877. And DSH itself runs the agent, loading the plugin as a profile bundle.

The addon side is tightly constrained. Only the bundled addon is supported, version 1.10 with module name dsh_blender_bridge, and the upstream alternatives are explicitly not supported since v2.3, where the old dual-name and category-action adapters were deleted. If you have one of those installed, the README tells you to disable it and install the bundled addon instead, with a migration document for the details.

What the addon provides is listed explicitly: ping, get_scene_info, get_world_state_snapshot, get_object_info(name), get_viewport_screenshot and execute_code(code), plus five optional asset integrations, PolyHaven, Hyper3D, Sketchfab, Poly Pizza and Hunyuan3D. Those asset integrations are the reason the addon has to run inside Blender rather than beside it, since they add and fetch actual 3D assets.

The backend is what the agent actually talks to, and its HTTP endpoints on 9877 are the diagnostics you will spend time with: a health endpoint that also reports provenance, asking whether the running process is the disk copy, a doctor endpoint that performs a full round trip through bpy, and a who endpoint reporting the write lease and channel metrics.

The fifteen tools, and the latency figures that justify them

The README publishes a table of capabilities with tools and typical latencies, and the numbers are the argument for the design.

Reading the viewport through blender_rt_see takes 50 to 100 milliseconds. Rendering from an arbitrary angle with blender_rt_see taking from, look_at and related arguments takes 85 to 280 milliseconds, and the description is careful that this needs no camera object and leaves the user's viewport untouched. Changing one thing and verifying it with blender_rt_do and see:true takes about 105 milliseconds.

Two entries stand out. blender_rt_watch samples within a time window and returns within six frames per call, which is how the agent checks whether something moved rather than taking a fresh render. blender_rt_loop is an inner-loop search running at 160 ticks per second with zero model turns, which is the important number: the iteration happens inside Blender, so a search across thousands of candidates does not cost one model turn per candidate.

The rest of the table is infrastructure. blender_rt_cmd and blender_rt_commands pass through addon commands and list them, at 25 to 55 milliseconds. blender_rt_perf does render performance profiling and presets, taking about 10 to 20 seconds to analyse. blender_rt_opt does object decimation with a safe join and no geometry loss, at roughly 1.4 milliseconds per object. blender_rt_headless spawns a separate headless process for heavy renders and batch geometry, with a cold start of 0.9 to 1.2 seconds, and blender_rt_worker keeps a hot headless session alive so you pay that cold start once rather than per job.

Then the higher-level pieces. blender_rt_plan is the contract layer and planner, covering 28 families and 186 plan operations, with an AABB sweep at 24 milliseconds and a BVH at 0.17 milliseconds per pair across 307 objects. blender_rt_txn provides transactions and rollback, with a snapshot of 96.7 MB in 824 milliseconds for 300 objects. blender_rt_preset is a preset library for saving, applying and exporting parameter sets. blender_rt_job is the job layer for work longer than one wait window, where op=wait returns the structured result rather than losing it. And blender_viewport handles channel health, the write lease and one-call Blender launch.

Selection moved into Blender, and what was removed to do it

Version 2.3 is the pivot point in this plugin's history, and the README devotes a block to it because it was a reversal.

Selection moved into Blender. You now pick objects natively in Blender, in multi-select or collection mode, and send them into the DSH draft with a button on the N panel. The activity state has four values, human, agent, idle and both, so both sides of the session can see who is driving.

What was removed is the more interesting half. The DSH-side viewport panel, the click-to-message interaction and blender_rt_pick were all deleted. In other words, the earlier design had the agent asking Blender what was selected; the current design has the human tell Blender, and Blender tells the agent.

The README's summary of the intent is worth quoting in substance: you pick objects in Blender natively and send them into the DSH draft with one button. The agent then works on what you gave it rather than on what it could guess you meant, and the guess is the step that goes wrong in an agent-driven GUI.

That is a reasonable trade, and it has a cost. An agent that can no longer pick objects cannot, for instance, iterate over the scene by selecting each object and inspecting it. It has to work through the contract layer and the planner instead, which is where the 28 families and 186 operations come in, and where the AABB and BVH timings live.

The bundled addon version moved in step. Version 2.3.0 added the native selection with multi-select and collection modes plus human and agent activity, and removed the viewport panel and the old addon support. Version 2.4.0 added sub-element selection, meaning points, edges, faces, bones and curve points, and made the N panel list resizable. Version 2.5.0 pinned the activity state to the top, added the ability to pause AI operations, and added environment and model API panels, with the addon at v1.10 and the protocol at 11.

The bundled modeling skill and how it registers

Since version 2.2.0 the package ships a skill named blender-modeling under skills/blender-modeling/, and it registers itself with DSH's skill registry as a bundled provider when the plugin loads. After installing the plugin and restarting DSH, the skill appears in the session skill catalog and the model loads it on its own for modeling and assembly work.

What is inside it is specified: a shape decision tree, 24 numbered recipes, the six pitfalls, the numeric-gate checklist and the multi-agent coordination protocol. The decision tree and the recipes are the model-facing content, and the numeric gate is interesting because it suggests the skill teaches the model to check measurable conditions rather than to judge by eye.

The precedence rule is the part that matters for anyone already using this. The bundled skill has rank 600, and a copy you installed yourself under ~/.dsh/skills/blender-modeling has user rank 400, which still wins. The stated reason is that existing users are never force-updated. If you keep your own copy, the plugin will not overwrite it on upgrade, and you will not silently get new recipes from the bundled version.

The skill is not DSH-specific. For other hosts, Claude Code, Codex, Cursor and similar tools, the same directory is a plain skills/<name>/SKILL.md bundle, and you link or copy it to that host's skill root. That is a deliberate choice to make the same content usable across agent runtimes rather than locking it to one.

The detailed walkthrough, configuration reference, deployment procedure and the v2.3 contract additions all live in the docs/ directory of the repository, with the walkthrough in Chinese.

Installation, and the doctor check that decides everything

The requirements are narrow and specific. Blender 4.x or 5.x running in GUI mode, because the channel needs a live GUI session and the -b flag is only used by the headless tools. The bundled addon, and only the bundled addon. Node.js 20 or newer to run the backend. And DSH, since this package is a DSH plugin that declares a bundle via cordis.patch.yml.

On operating systems, the README says a WSL host with Windows Blender needs WSL interop, which is on by default, and that same-OS setups on Windows, native Linux or macOS are supported and auto-detected.

You only need a DSH source checkout if you are rebuilding, with the build command taking a DSH_CHECKOUT environment variable. The repository commits lib/, so a plain clone is ready to install.

The install steps themselves are in the README as a five-part shell sequence, and the parts worth calling out are the last two.

Step 3 is installing into DSH as a profile bundle. The package declares dsh.bundle, and you symlink it into the profile's node_modules under @dsh-external, add a link: entry with an absolute path to the profile package.json dependencies, and add the package name to dsh.profile.bundles. There is a dry run for this, dsh --profile <profile> --dump-config, and then you restart DSH.

Step 4 is starting Blender and connecting the addon, with two routes. For an agent or unattended setup, blender_viewport with op=launch boots a script, spawns Blender and polls port 9876, and is idempotent. For a manual setup, you start Blender, press N, choose DSH Blender Bridge and Connect.

Step 5 is the verification, and the README is emphatic that there is only one acceptance criterion: doctor returns kind=ok, and if it does not then the thing is not installed.

The three commands to run are:

curl -sS http://127.0.0.1:9877/health
curl -sS http://127.0.0.1:9877/doctor
curl -sS http://127.0.0.1:9877/who

The health endpoint reports whether the running process is the disk copy, the doctor endpoint does a full round trip through bpy, and the who endpoint reports the write lease and channel metrics. The point of a single acceptance criterion is that there is no ambiguity about whether the setup worked.

There is also a no-build route. The README points to a release tarball, dsh-external-dsh-blender-plugin-2.5.0.tgz, at 1.3 MB and 142 files, which you unpack into the profile's node_modules or install with npm i on the tarball, with the skill included inside it.

Limits: an agent with Python inside your Blender

The limits are worth being blunt about, and most of them follow from the architecture.

The first is that the agent can execute arbitrary Python inside Blender. execute_code(code) is one of the addon's primitives, and the plugin's whole premise is that a language model drives the application. That is the feature, and it is also the risk: a model that writes Python against a live Blender session can do anything Blender can do, including destructive edits to your scene and your files. The transaction layer with rollback and the snapshot mechanism are the mitigation, and the write lease in blender_viewport is a coordination point, but neither is a sandbox.

The second is the coupling to DeepSeek Harness. The package is a DSH plugin, with inject of tools, a dsh.bundle declaration and peer dependencies on the DSH LLM and tools packages at version 0.0.1-rc or newer below 2. The skill's bundled registration mechanism is DSH's skill registry, and the entire tool naming convention is designed around that host. The skill directory works elsewhere as a plain SKILL.md bundle, but the plugin itself does not.

The third is that the addon requirement is absolute and narrow. Since v2.3 the upstream MCP for Blender addons are not supported, and if one is installed the plugin will not work correctly until you disable it. For someone arriving from the MCP-style tooling this is a step backwards in interchangeability.

The fourth is the version churn. Three releases on a single day, v2.3.0, v2.4.0 and v2.5.0, with the addon moving to v1.10 and the protocol at 11 in the same window, and a MIGRATIONS.md that you need to read. The project is moving fast enough that a configuration you verified last week may need checking again.

The fifth is the platform reach. The published tarball is a single artefact for the listed systems, and the WSL interop requirement is a real constraint for teams that split Windows tooling and Linux agents.

This plugin against MCP-style Blender integrations and against scripting Blender yourself

Two comparisons make the choice clearer.

The first is against the MCP for Blender family of addons, which this plugin used to sit alongside and now explicitly does not support. The difference in approach is where the interaction loop lives. An MCP server exposes Blender's capabilities as tools over a protocol, and the agent drives them from its own process. This plugin runs a Node backend that maintains a persistent channel to a Blender addon, and it keeps the connection state, the write lease and the session alive in between calls.

The practical differences follow from that. blender_rt_loop running an inner search at 160 ticks per second with zero model turns is only possible because the iteration runs inside Blender with the channel staying open. A hot headless session in blender_rt_worker exists for the same reason. And the selection model is different in kind: with MCP the agent asks what is selected, here the human pushes the selection across.

The second comparison is against scripting Blender directly, with a Python script or a bpy script run from the command line. That approach is simpler, fully deterministic and has no agent in the loop, and for a known modelling task with a known answer it is the better tool. What it does not do is decide what to build, adapt the plan after looking at the result, or iterate across a search space without a model turn per step. The plugin's value is entirely in that adaptive part.

The honest framing is that this is a tool for a specific workflow, someone who knows Blender and wants to direct a model inside it, rather than a general way to build 3D content. The bundled modeling skill with its decision tree and numbered recipes is a strong hint that the intended user is a modeller rather than a prompt engineer, since the skill exists to give the model the domain knowledge that the modeller would otherwise have to write into every prompt.

Editorial conclusion

Adopt this plugin if you want an AI agent to operate a Blender session you keep an eye on, and you are willing to run a Python addon inside Blender that executes agent-written code. Do not adopt it if you want the agent fully hands-off, since the design deliberately keeps a human in the loop on selection. Verify first that doctor returns kind=ok, that the bundled DSH Blender Bridge addon is the one installed rather than an upstream alternative, and that the bundled skill has not been overridden by a copy in your own skills directory without you meaning it.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. sixtysevenlf/dsh-blender-plugin on GitHub