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.