Windows PC Agentic Blender

Drive Blender headless from your PC with an authenticated JSON-RPC agent, watch your scene build live in a browser viewport, and let the Pi /blender skill do the modeling. Windows 10/11 adaptation of android-agentic-blender: official x64 Blender (no source builds), PowerShell lifecycle, optional GPU Cycles (OptiX/CUDA/HIP/oneAPI).

Pi / browser  ──HTTP :8088──▶  viewer/app.py  ──JSON-RPC :8766──▶  blender.exe --background
                                 ▲ solid preview, gallery                │
                                 └── PNG renders, .blend  ◀── Geometry Agent (bpy, Cycles GPU/CPU)

Install as a Pi plugin

Load the /blender skill into Pi on any PC with one command:

pi install https://git.cyfrowynomada.com/CyfrowyNomada/windows-pc-agentic-blender.git

Then clone the toolkit itself and run its setup (details in Install as a Pi plugin on other PCs).

Requirements

• Windows 10/11 x64
• Blender — installer or portable zip
• Python 3.10+ and Git on PATH

First-time setup

cd windows-pc-agentic-blender
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

That pins and patches the Geometry Agent, probes for blender.exe (installed location, .deps\blender\blender.exe, or pass install-agent.ps1 -BlenderPath C:\...\blender.exe), generates the RPC token into config\agent.env, installs the optional MCP bridge, and runs the doctor check. Re-run any time; it is idempotent.

Everyday use

.\viewer\start.ps1             # starts Blender (headless) + viewer, opens http://127.0.0.1:8088
.\runtime\status.ps1           # is the agent alive?
.\viewer\refresh.ps1           # regenerate the solid preview now
.\viewer\publish-final.ps1 render.png   # feature a render in the Final tab
.\viewer\stop.ps1              # stop the viewer (Blender keeps running)
.\runtime\stop-blender.ps1     # stop the Blender agent

Everything binds to 127.0.0.1 only. Renders and .blend files land in %USERPROFILE%\Documents unless you change BLENDER_OUTPUT_DIR; every PNG/JPEG/WebP there (except names containing _test) shows up in the viewer's Gallery automatically.

The viewer

• Solid Preview — an instant software isometric projection of the current scene. It refreshes by itself whenever the scene changes; it never spends Cycles samples.
• Final Render — whatever you publish with viewer\publish-final.ps1 or a script.
• Gallery — auto-indexed renders from the output directory.

The Pi skill

From this checkout, one prompt does the whole job — starts the stack, models the scene, validates meshes, renders QC previews, saves the .blend, and leaves services running:

/blender Create a modular industrial gate with working doors and three-quarter QC renders

The skill follows the sbf.md design template and the evidence-based quality loop: fixed judgeset cameras, rendered-pixel verification, regression tracking. While it works, watch the viewer.

Talking to the agent directly

All operations are authenticated JSON-RPC over a newline-delimited socket. The standard-library CLI:

python .pi\skills\blender\scripts\rpc.py status "{}"
python .pi\skills\blender\scripts\rpc.py scene.summary "{\"limit\":5000}"
python .pi\skills\blender\scripts\rpc.py scene.save "{\"path\":\"C:/Users/you/Documents/asset.blend\"}"
python .pi\skills\blender\scripts\rpc.py batch.execute "@job.json"     # batched geometry calls
python .pi\skills\blender\scripts\rpc.py render.preview "@render.json" # QC render

Full operation reference: docs/GEOMETRY_AGENT.md and .pi/skills/blender/references/geometry-api.md. Ready-made scenes: python examples\scenes\build_cute_room.py (plus kitchen, sims house, portfolio — run while the agent is up).

MCP (optional)

.\runtime\run-mcp.ps1   # stdio bridge; point your MCP client at this script

Install as a Pi plugin on other PCs

This repository is itself a pi package (package.json manifest, pi-package keyword): it ships the /blender prompt, the blender skill, the SBF template, and the authenticated RPC helper. On a new PC:

# 1. Pi plugin (skills + prompt load into every pi session)
pi install https://git.cyfrowynomada.com/CyfrowyNomada/windows-pc-agentic-blender.git   # or: pi install C:\path\to\local\clone

# 2. The toolkit itself (Blender lifecycle + viewer live here)
git clone https://git.cyfrowynomada.com/CyfrowyNomada/windows-pc-agentic-blender.git $env:USERPROFILE\Documents\windows-pc-agentic-blender
cd $env:USERPROFILE\Documents\windows-pc-agentic-blender
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

The skill finds the toolkit automatically when it is cloned to %USERPROFILE%\Documents\windows-pc-agentic-blender (or via the checkout it lives in); otherwise set BLENDER_SUITE_ROOT to the toolkit path. Verify with /blender or python .pi\skills\blender\scripts\rpc.py status "{}".

Configuration (config/agent.env)

Key	Default	Meaning
BLENDER_AGENT_HOST / BLENDER_AGENT_PORT	127.0.0.1 / 8766	Geometry Agent endpoint
BLENDER_AGENT_TOKEN	random	Bearer token; every request must carry it
BLENDER_BIN	probed	Path to blender.exe
BLENDER_OUTPUT_DIR	%USERPROFILE%\Documents	Renders, gallery, revision file
BLENDER_CYCLES_SAMPLES	128	Default final-render samples
BLENDER_CYCLES_DEVICE	NONE	OPTIX, CUDA, HIP, ONEAPI for GPU Cycles; NONE/CPU for CPU
BLENDER_USE_DENOISING	0	1 enables Cycles denoising
BLENDER_START_FILE / BLENDER_OPEN_FILE	empty	.blend to open on startup
BLENDER_NEW_FILE	0	1 starts factory-empty (the Pi skill uses this)
VIEWER_HOST / VIEWER_PORT	127.0.0.1 / 8088	Viewer endpoint

Change the token or port → restart: runtime\stop-blender.ps1 then viewer\start.ps1.

Troubleshooting

• "Authentication failed" — the running agent has an older token than config\agent.env. Restart the agent.
• RPC calls hang or port already in use — something else on your machine may hold BLENDER_AGENT_PORT (another Blender-based app will happily squat on 8765). Check netstat -ano | findstr 8766, pick a free port in the config, restart.
• "blender.exe not found" — install Blender, or run scripts\install-agent.ps1 -BlenderPath C:\path\to\blender.exe.
• GEOMETRY_AGENT_GPU_UNAVAILABLE in the log — the selected BLENDER_CYCLES_DEVICE isn't supported by your GPU/driver; rendering falls back to CPU. Try CUDA/OPTIX per vendor.
• Viewer shows "Blender offline" — runtime\status.ps1 to check the agent; viewer\start.ps1 starts both.
• General health check — powershell -ExecutionPolicy Bypass -File scripts\doctor.ps1.

Logs and PID files live in .run\.

Security

• Both services bind to loopback only; every request needs the random token; config\agent.env is ACL-restricted to your user and ignored by Git.
• Arbitrary Python RPC (python.execute) is disabled in the runtime.
• Don't expose the ports without an authenticated reverse proxy.

Layout

config/       agent.env.example → agent.env (token, ports, paths)
runtime/      Blender agent lifecycle (start, stop, status, MCP bridge)
viewer/       loopback web viewer (solid preview, final render, gallery)
scripts/      setup, install-agent, install-mcp, doctor
examples/     procedural scene + portfolio scripts
patches/      headless extensions to the pinned Geometry Agent
.pi/          Pi prompt + blender skill (SBF template, RPC CLI, quality loop)

MVP 0.1.0 — see CHANGELOG.md and THIRD_PARTY.md.