Build in Blender. See it in Spatial.

Your agent can script Blender, publish a first shape, refine it, and update the same object in Spatial. You can move or resize that object between edits. Its placement survives the next geometry update. The integration uses a persistent headless Blender process on the agent’s execution computer. The inference provider and the browser displaying Spatial can be on different machines.

Put Blender on the execution host

Start with a connected Spatial session and current versions of the Python Entity worker and Spatial gateway. Discover ar_blender and ar_world in the running registry. Ask the agent to inspect get_execution_context, then:

{ "name": "ar_blender", "arguments": { "command": "capabilities" } }

The result reports installation discovery and the execution workspace. If Blender is missing, install it on that host using your normal package or deployment process. For a Railway execution host, Blender belongs on Railway; opening Spatial on your laptop does not make your laptop the execution host. The integration does not install Blender automatically. The execution RPC server must support the blender action. A configured remote execution route does not silently fall back to another computer when Blender work fails. Make blender available on the execution host’s PATH, or set NGRAM_BLENDER_EXECUTABLE there. You can also supply the installed executable’s full path in each execute or publish payload. A path supplied for one call is not remembered as the default for later calls. capabilities discovers PATH and the environment override, so a portable installation outside them may still report installed: false.

Blender Python has the same trust boundary as the agent’s shell tools on that host. The Spatial browser receives model artifacts; it does not execute the Blender script.

Create a project

The following blocks are agent tool calls, not terminal commands. They assume blender is discoverable on the execution host.

{
  "name": "ar_blender",
  "arguments": {
    "command": "create",
    "payload": { "project_id": "ring_study", "name": "Ring study" }
  }
}

Project IDs use letters, numbers, underscores, or hyphens, up to 64 characters. Continue an existing project with execute; calling create with its ID again is rejected. An optional blend_file imports a .blend file already inside the execution workspace.

Publish a first model

{
  "name": "ar_blender",
  "arguments": {
    "command": "execute",
    "payload": {
      "project_id": "ring_study",
      "position": [0, 0, -2],
      "source": "bpy.ops.mesh.primitive_torus_add(major_radius=0.35, minor_radius=0.045, major_segments=48, minor_segments=12, location=(0, 0, 0.45), rotation=(1.57079632679, 0, 0))\nring = bpy.context.object\nring.name = 'Ring'\nfor face in ring.data.polygons: face.use_smooth = True\npublish()\nbpy.ops.mesh.primitive_cube_add(size=1, location=(0, 0, 0.04))\nbase = bpy.context.object\nbase.name = 'Base'\nbase.scale = (0.55, 0.3, 0.08)\nresult = {'objects': len(bpy.context.scene.objects)}"
    }
  }
}

bpy and publish() are available to the script. This example publishes the ring first. A successful script automatically publishes again after adding the base. Set result to a small JSON-compatible value for inspection output. position places the first Spatial preview in world coordinates; choose clear space in your scene. Blender authoring uses Z up. GLB export converts it to Spatial’s Y-up coordinates while preserving authored metre scale and origin.

Refine it while it stays in the scene

Move or resize the model in Spatial, then ask the agent to run this edit on the same project:

{
  "name": "ar_blender",
  "arguments": {
    "command": "execute",
    "payload": {
      "project_id": "ring_study",
      "source": "ring = bpy.data.objects['Ring']\nring.scale = (1.15, 1.15, 1.15)\nresult = {'ring_scale': list(ring.scale)}"
    }
  }
}

The .blend scene persists between edits and reopens from its latest published checkpoint after a process restart. Reacquire objects through bpy.data after restarting; arbitrary Python variables from the old process do not survive. Each publish writes an immutable .blend, a self-contained GLB preview, and a snapshot. The connected surface receives the revision and loads the preview through the authenticated bridge and gateway. The old visible mesh stays in place while its replacement loads. Position, rotation, and scale are preserved; updates queue while a human holds the object or pauses its updates. This is live preview delivery at publish checkpoints. It does not stream every Blender viewport frame. Put publish() at meaningful stages of a long build. Transport polling delivers those stages without extra model calls.

Inspect the actual result

Use ar_blender with command: "status" and the project ID for host state and the last snapshot. Use ar_world observe for the Spatial asset’s loading, ready, or failed state. A completed export alone does not prove the browser rendered it. The stable Spatial ID is blender.<shell-slug>.<project-id>. Inspect the actual ID before using it in a program. The Programs guide shows how to add a turn toggle or speed slider without repeated inference. If no surface is connected, the project still saves on the execution host. Use command: "show" with the project ID to attach it when Spatial reconnects. Deleting an object in the current scene detaches that live link; subsequent previews do not undo your deletion.

Control and keep your work

Select the model in Objects:

Control	Effect
Pause updates	Hold the displayed preview while Blender may continue working
Resume updates	Check the host and display the newest available revision after release
Refresh project	Read the current host state and revision
Stop Blender	Terminate that project’s process and retain its last published checkpoint
Download .blend	Keep the editable Blender checkpoint
Download GLB	Keep the published model artifact

The agent can also use ar_blender stop. Cancelling an active Blender tool call stops its matching job. Neither Stop Blender nor closing a browser tab is the global inference pause. Projects live under .ngram/blender/<project-id>/ inside the execution workspace. Keep that workspace on durable storage, and back up project artifacts separately from browser scene exports. An idle project process remains available until stopped; stop it when you want to release its resources.

Compatibility and failures

The live desktop pipeline was verified with Blender 4.5.3 LTS, including intermediate previews, preserved transforms, cancellation, and checkpoint reopening.
Keep each preview below 32 MB and imported geometry below 100,000 vertices. Use self-contained assets; the loader rejects external GLB resources.
The default edit timeout is 1,800 seconds; a payload can set timeout between 1 and 86,400 seconds. One edit runs at a time per project.
A failed or stopped edit retains published checkpoints. Unsaved changes since the last publish are lost when the process terminates.
Authored materials and exportable animation can travel through GLB. The renderer plays the first imported animation clip while creations are running. Blender-specific rendering features, lights, and cameras are not a complete scene transfer.

For a failed preview, inspect its asset error, simplify unsupported or oversized content, and publish another revision. Reload asset retries the current URL. For a missing executable, fix the installation on the reported execution host before retrying.

Getting started

Build

Reference

Build in Blender. See it in Spatial.

Put Blender on the execution host

Create a project

Publish a first model

Refine it while it stays in the scene

Inspect the actual result

Control and keep your work

Compatibility and failures

​Put Blender on the execution host

​Create a project

​Publish a first model

​Refine it while it stays in the scene

​Inspect the actual result

​Control and keep your work

​Compatibility and failures

Put Blender on the execution host

Create a project

Publish a first model

Refine it while it stays in the scene

Inspect the actual result

Control and keep your work

Compatibility and failures