plumber-agent 1.1.1

Local DCC Agent for Plumber Workflow Editor - Enables Maya, Blender, and Houdini operations

Plumber Agent

Local DCC agent for Plumber Workflow Editor.

Keeps Maya, Blender, Houdini, and Nuke running as persistent background servers so Plumber workflows send operations in ~100ms instead of cold-starting the DCC every time (25–200x faster).

---

Requirements

• Python 3.8, 3.9, 3.10, 3.11, or 3.12
• pip
• At least one DCC application:
  • Maya 2022–2026 (requires mayapy on PATH, or auto-discovered)
  • Blender 4.0–5.0+ (auto-discovered from standard install locations)
  • Houdini 20.0+ (requires hython on PATH, or auto-discovered)
  • Nuke 13–15 (requires nuke on PATH, or auto-discovered)

---

Install

pip install plumber-agent

Upgrade:

pip install --upgrade plumber-agent

---

Run

Start the agent in the foreground (useful for first-time setup and debugging):

plumber-agent

The agent starts on http://127.0.0.1:8001, connects to the Plumber cloud backend, and auto-discovers your installed DCC applications. A status line is printed for each DCC found:

[OK] Maya 2026 detected at /usr/autodesk/maya2026/bin/mayapy
[OK] Blender 4.4 detected at /Applications/Blender.app/Contents/MacOS/Blender
[--] Houdini not found

Windows Service (recommended for beta testers)

Run the agent as a background Windows Service that starts automatically with Windows:

# Run as Administrator
plumber-agent install-service
plumber-agent start
plumber-agent status

Service management:

plumber-agent stop
plumber-agent restart
plumber-agent logs          # tail the log file
plumber-agent uninstall-service

macOS / Linux background process

plumber-agent &             # run in background
plumber-agent logs          # check logs

---

Custom Nodes

Place Python files in ~/plumber/custom_nodes/ and they appear automatically in the editor's node menu. No restart required — the agent hot-reloads when files change.

~/plumber/
  custom_nodes/
    my_studio_node.py    ← your nodes go here
    vfx_pipeline.py

See the SDK documentation for the full API reference.

Minimal example (~/plumber/custom_nodes/hello.py):

from plumber_sdk import Node, Property, Output, ExecutionContext

class HelloNode(Node):
    _description = "Greet the world"
    _category = "Examples"

    name: str = Property(default="World", label="Name")
    greeting: str = Output(type=str, label="Greeting")

    def execute(self, context: ExecutionContext) -> dict:
        return {"greeting": f"Hello, {self.name}!"}

---

Diagnostics

plumber-agent version       # print installed version
plumber-agent discover      # list detected DCC applications
plumber-agent status        # show running service status and active sessions
plumber-agent logs          # stream the log file

Log file location:

• Windows: %LOCALAPPDATA%\plumber-agent\plumber_agent.log
• macOS / Linux: ~/.plumber-agent/plumber_agent.log

---

Workspace Variables

Workflows can reference portable paths using $VAR placeholders:

plumber-agent set-var PROJECTS /mnt/studio/projects
plumber-agent set-var RENDERS  /mnt/studio/renders
plumber-agent list-vars

In a workflow, use $PROJECTS/my_shot/scene.ma and the agent expands it to the full path on each machine. This lets one workflow JSON run correctly across different artists' workstations.

---

Troubleshooting

Agent not connecting to the editor

• Confirm plumber-agent status shows running.
• Check firewall rules — the agent needs outbound HTTPS to plumber-production-446f.up.railway.app (port 443) and WebSocket on the same host.

DCC not discovered

• Maya: ensure mayapy is on your PATH, or set MAYA_LOCATION.
• Blender: install to the default location for your OS; the agent scans standard paths.
• Houdini: ensure hython is on your PATH (sourcing houdini_setup does this).
• Nuke: ensure nuke is on your PATH.
• Run plumber-agent discover to see exactly which paths were scanned.

Custom node not appearing

• Confirm the file is in ~/plumber/custom_nodes/ with a .py extension.
• Run plumber-agent logs and look for import errors — a syntax error in your file prevents all nodes in that file from loading.
• Make sure the class inherits from Node or one of the DCC base classes.

DCC operation is slow or times out

• The first operation in a workflow warms up the persistent server (~1–10 s depending on DCC). Subsequent operations in the same session should be ~100 ms.
• Increase timeout in _run_raw_script() for heavy renders or exports.