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.

Layer	Responsibility
Entity worker	Run the agent’s turn, dispatch Blender commands, and receive rendered images
Execution host	Run Blender Python, preserve projects, render views, and export artifacts
Spatial gateway and browser	Deliver artifacts, display revisions, and handle human interaction

On a hybrid setup, your browser can run locally while Blender and its durable files stay on Railway. The model provider does not need filesystem access to the browser computer.

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 an execute, publish, or render payload. The project remembers that path. capabilities checks PATH, the environment override, remembered project paths, and portable installations under the execution workspace’s tools/blender*/blender.

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.

See what you build

ar_blender render returns a rendered image to the agent in the current tool result. It uses the existing execution host and does not publish a new mesh revision. For an existing project:

{"name":"ar_blender","arguments":{"command":"render","payload":{"project_id":"ring_study","options":{"style":"studio","orbit":[35,20],"size":1024,"samples":32}}}}

Inside an execute script, call render_view(style="studio", orbit=[35,20]) to return a working view alongside the normal published preview. Up to four views from that script are attached to its tool result. Camera and lighting settings used for inspection are temporary. Compare the Blender result with ar_request_capture to inspect the material and geometry as the Spatial renderer actually displays them. See Vision for camera control, close-ups, diagnostic views, and the human’s view-sharing toggle.

Review option	Use
`objects`	Frame one to 64 named Blender objects
`camera`	Use an authored camera by name
`position`, `look_at`	Choose an explicit camera pose in Blender Z-up metres
`orbit`, `distance`	Orbit in degrees and distance in metres around the subject
`style`	`scene` uses authored lighting; `studio` supplies review lighting; `clay` emphasizes shape
`projection`	`perspective`, `orthographic`, or `equirectangular`
`size`, `samples`	Ordinary views: 256–1536 pixels; samples: 1–256

The execution host renders with CPU Cycles. Choose a small view while iterating, then increase resolution and samples for the final inspection. Returning an image requires an image-capable model and transport; a text-only receipt does not mean the agent saw the render.

Build the surrounding environment

The same project can produce a 360-degree sky. Author scenery, lighting, or a Blender World shader, then call:

{
  "name": "ar_blender",
  "arguments": {
    "command": "render",
    "payload": {
      "project_id": "ring_study",
      "options": {
        "projection": "equirectangular",
        "style": "scene",
        "position": [0, 0, 1.6],
        "look_at": [0, 1, 1.6],
        "size": 2048,
        "samples": 32
      }
    }
  }
}

This places the panorama camera at a standing viewer’s height, facing Blender’s positive Y axis. Choose the position appropriate to your scene. An equirectangular render captures every direction, so place the camera outside foreground geometry. World-only scenes are supported. The result includes an image plus a skybox configuration. Pass the returned skybox object directly as the payload of ar_environment configure. Spatial loads it through the existing authenticated artifact route. Use environment controls to adjust its rotation, visible brightness, reflections, lighting, and fog. Panoramas require style: "scene", which is also their default. size is an even width from 256 through 4096, defaults to 2048, and produces a 2:1 JPEG. The helper temporarily changes the camera and render settings, then restores them. It does not publish another GLB revision. Imported HDR and EXR sky images are supported separately by Spatial; this helper does not export HDR. Keep distant scenery in the panorama and nearby, touchable objects in real geometry. A sky image has no collision or positional parallax. A Blender mesh with a Figment can be picked up, thrown, programmed, and shared. After applying the sky, capture the actual Spatial view to evaluate the complete scene. Panorama rendering and ar_environment require the updates on main after v1.0.1, across the worker, execution backend, and gateway.

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. To make the model a complete interactive object, attach a Figment. Its grips can reference uniquely named GLB nodes, and its physics can use compound colliders independent of the visible mesh. Mesh revisions retain this definition. Publishing a linked Figment includes the matching editable Blender source alongside its geometry and behavior. 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

See what you build

Build the surrounding environment

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

​See what you build

​Build the surrounding environment

​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

See what you build

Build the surrounding environment

Inspect the actual result

Control and keep your work

Compatibility and failures