dsh-plugin-blender

Blender for DeepSeek Harness: the agent renders 3D models headlessly through Blender, and the workbench gets a 3D Viewer panel in the right sidebar that loads the exported models with three.js and shows the rendered images.

Host half: three model tools plus two HTTP routes. Client half: one sidebar tab. No runtime dependencies — the host uses node builtins, and the panel is one prebuilt bundle.

---

What it adds

Three model tools.

Tool	Purpose
blender_status	The executable in use, its version, the work directory, and how many models/renders the panel lists.
blender_render	Render a 3D file to a PNG and return the image to the model. .blend files keep their own camera and lights; imported files are framed automatically.
blender_export_glb	Convert any supported file to .glb and publish it to the viewer panel.

One sidebar tab. blender-viewer-tab in the right sidebar: a three.js canvas with orbit/zoom controls, a model picker, and a strip of Blender's renders (click one to view it full-panel).

Two HTTP routes. GET /blender/models lists what the panel may show; GET /blender/file/<id> serves an already-scanned file. A request can only name an id, never a path, so the routes cannot read outside the scanned directories. They are registered on the web server directly, so they carry no session token: with the default loopback bind only this machine can reach them, but a server bound to 0.0.0.0 exposes the listed files to that network — set enableViewer: false in that deployment.

One Cordis service. ctx.blender exposes detect(), version(), listModels(), render(request, signal) and convertToGlb(request, signal).

---

Architecture

┌─ Host (Node) ──────────────────────────────────────────────┐
│  lib/index.js     Cordis plugin: name/inject/apply, routes │
│  lib/tools.js     the three defineTool definitions         │
│  lib/blender.js   detection, subprocess runner, registry   │
│  lib/scripts/render.py       bpy: import, frame, render    │
│  lib/scripts/convert_glb.py  bpy: import, export GLB       │
└──────────────────────────┬─────────────────────────────────┘
                           │  /blender/models, /blender/file/<id>
┌──────────────────────────┴─────────────────────────────────┐
│  src/client.jsx   tab type + slot registrations            │
│  lib/client.js    built bundle (three.js inside)           │
└─ Browser (web shell) ──────────────────────────────────────┘

Blender is driven as blender -b --factory-startup -noaudio --python <step> -- <json>; each step prints one DSH_BLENDER_RESULT {json} line, which the host parses. Rendering defaults to Cycles on CPU, the reliable headless engine; EEVEE and Workbench are available but need a GPU.

Cycles renders on CPU, so an unattended blender_render works on a headless host. A 960x720x32-sample render of a simple model takes well under a second.

The panel loads .glb, .gltf, .obj, .stl and .ply directly. Everything else (.blend, .fbx, .dae, .usd, .abc) must go through blender_export_glb first, and the panel marks those entries.

---

Requirements

• DeepSeek Harness 0.1.5 or a compatible 0.1.x with the web profile
• Node.js 20 or newer
• Blender 3.6+ (4.x recommended) — headless works, no display needed

Blender is optional at load time: without it, the tools still register and fail with an actionable message, and the panel still lists any .glb files that are already in the models directory.

Installation

The host resolves @deepseek-ai/dsh-tools from the profile dependency closure, so the package must live there as a real directory; a symlink would move its realpath out of the closure and break that import.

From GitHub (one command, any machine)

package.json declares dsh.bundle with cordis.patch.yml, so the repository installs as a profile bundle and the plugin row is composed automatically. lib/client.js is committed prebuilt, so nothing is compiled on install.

dsh plugin --profile web add github:<owner>/dsh-plugin-blender

Then restart dsh web (a bundle install changes the tree, which the live patch watcher does not cover). Blender must be installed on that machine; everything else is in the package.

From a local checkout

SRC=/path/to/dsh-plugin-blender
cd "$SRC" && npm install && npm run build     # produces lib/client.js
npm run deploy                                 # copies lib/ into $DSH_HOME/profiles/node_modules/dsh-plugin-blender

Then add one row to $DSH_HOME/profiles/web/cordis.patch.yml:

- insert:
    - id: blender
      name: 'dsh-plugin-blender'

The shipped web profile uses patchReload: live, so the row is picked up without a restart. Editing a plugin's lib/ afterwards is not watched — re-run npm run deploy and restart dsh web after changing host code.

The tab opens itself once a session exists. It can also be opened by hand from the right sidebar's + page ("3D Viewer").

Publishing (maintainers)

GITHUB_TOKEN=... npm run publish:github    # creates the repo, sets the dsh-plugin topic, pushes
GITHUB_TOKEN=... npm run publish:market    # forks the registry and opens the entry PR

The token is a classic PAT with repo (or public_repo) and read:user. The market lists one YAML entry per plugin (data/plugins/<owner>__<repo>.yml) and requires the repo to declare dsh.bundle and to be at least one day old, so run the market step the day after the first push.

Blender detection

In order: the blenderPath config, $BLENDER_PATH, blender on PATH, then common installs (/usr/bin, /snap/bin, /opt, ~/.local/share/blender*, ~/.local/bin, macOS Blender.app, Windows Program Files). blender_status reports which one won.

---

Configuration reference

Key	Type	Default	Meaning
blenderPath	string	''	Explicit Blender executable. Empty means auto-detect.
workDir	string	$DSH_HOME/blender	Holds models/ and renders/. Created on load.
modelDirs	string[]	[]	Extra directories to list and serve in the panel (scanned 4 levels deep, 400 files max).
timeoutMs	number	300000	Per-render budget; the Blender process is killed when it expires.
defaultWidth	number	960	Default render width.
defaultHeight	number	720	Default render height.
defaultSamples	number	32	Default Cycles samples.
defaultEngine	string	cycles	cycles, eevee or workbench.
enableViewer	boolean	true	Register the viewer routes.

Every key is optional; a row needs only id and name.

---

Tools

blender_render

Argument	Meaning
file	Model or .blend to render.
output	Output path or file name; defaults to a timestamped PNG in workDir/renders.
width, height, samples, engine	Override the defaults for this render.
frame	Animation frame for an animated .blend.
camera	Camera name inside the .blend to render from.
transparent	Render with an alpha background.

A .blend renders through its own camera when it has one; otherwise (and for every imported format) the camera is placed to frame the geometry, and a key + fill light pair is added only when the scene has no lights. The PNG is saved, published as an attachment so a multimodal model actually receives it, and listed in the panel.

blender_export_glb

file plus an optional name; writes workDir/models/<name>.glb, strips cameras and lights, exports Y-up, and returns the geometry statistics.

---

Verification

npm run build     # lib/client.js
npm run verify    # structural checks on both halves
npm run client    # loads the bundle like the shell does, activates it, renders the panel
npm run smoke     # real headless Blender: convert, render, .blend render, HTTP routes
npm run viewer    # Chromium screenshot of the panel showing a Blender-exported model

npm run smoke writes a cube .obj and a .blend to a temp directory, converts and renders both, asserts the GLB magic and PNG signature, then serves the captured routes on a real socket and checks the listing, the content types, an unknown id (404) and a path-traversal attempt (404). npm run client evaluates lib/client.js through a stub module table, runs apply() against a stub shell context and server-renders the registered tab. npm run viewer bundles the real panel component for a standalone page, loads it in Chromium and screenshots the three.js canvas (written to test/viewer-shot.png). The Blender-dependent scripts exit 0 with a skip notice when Blender or Playwright is missing.

---

Troubleshooting

"Blender was not found" — install Blender, put it on PATH, or set blenderPath in the row config; blender_status echoes the path that was tried.

The panel shows "no models yet" — nothing has been exported. Ask the agent to run blender_export_glb, or drop a .glb into $DSH_HOME/blender/models.

The tab does not appear — confirm lib/client.js exists and was built, that the row's name matches the package name exactly, and that the deployed copy in the closure is the one you edited (npm run deploy). Host lib/ changes need a dsh web restart.

A model renders black or empty — a Cycles render of a file with no geometry fails with "the scene contains no mesh geometry to render". For imported files the auto-camera is computed from mesh bounds, so a file with only cameras, lights or empties cannot be framed.

Renders are slow — lower samples (8–16 is enough to judge a shape), lower the resolution, or use engine: workbench when a GPU is present.

License

MIT