Setting Up Nodes

Setting Up Nodes

A runner node runs test jobs on a machine other than the server. The server has a built-in runner, so nodes are optional; add them to spread load, to run on Windows, to sit closer to a staging environment, or to give the big suites a beefier box.

Nodes are bare node processes, not Docker containers. A node needs Node.js 22.22.1+ and (the first time) will install Playwright browsers, nothing else.

How it works

• A node registers itself with the server over HTTP and appears in Settings → Runners.
• The server dispatches a job to a node by POSTing the test payload to the node's URL; the node runs it with the project's own runner CLI and reports back.
• The queue serialises per node — one job at a time each — so parallel runs never step on one another.
• Control is HTTP-only (no socket.io from the server to nodes), which is what lets a node self-restart cleanly.

The registration secret

Every node must present PLUM_NODE_SECRET to register or to be controlled. Find it in Settings → Runners → Registration secret (owner only), or Plum prints it after plum server start. On the server host it lives in data/.plum-node-secret, which is where a co-located plum node start reads it from automatically. Regenerating it from that page invalidates every node's current secret; Plum pushes the new one to reachable nodes and names the ones it couldn't reach.

Registering a node

On the server machine

plum manage-nodes

An interactive menu: add a node, start/stop/restart, view status, regenerate the secret. Nodes started here reach the server at http://host.docker.internal:<port> because the server runs in Docker.

On another machine

PLUM_NODE_SECRET=<the secret> plum node start node-2

You're prompted for the server URL, this node's public URL (how the server will reach it), a port, and a browser. Pass --node-secret <s> instead of the env var if you prefer. --boot / --no-boot control whether the node is set to start on reboot.

Node commands

Command	Effect
plum node start [name]	Register and start a node here. --boot / --no-boot.
plum node list	This machine's nodes and their status
plum node restart [name]	Stop, refresh dependencies, restart
plum node stop [name]	Stop a node (stays registered)
plum node reconfig [name]	Re-enter a node's settings without starting
plum node delete [name]	Stop it, delete its config, unregister it. No name deletes every node on this machine.
plum manage-nodes	The interactive menu (server machine)

Node state lives in ~/.plum/nodes/<name>/. Runs auto-start on reboot when registered with --boot (or restart: unless-stopped semantics on the server).

Distributing a run across nodes

When a run targets more than one runner:

• Playwright shards natively — each lane gets --shard=k/N.
• Cucumber has no shard flag, so Plum chunks the selected tags across lanes instead.

The built-in server runner can be one of the lanes, or you can turn it off in Settings → Runners → Built-in runner to route everything to nodes.

Troubleshooting

• "Invalid registration secret" on plum node start — the Bearer value wasn't a JWT and didn't match PLUM_NODE_SECRET. Copy it fresh from Settings → Runners.
• A node shows offline — Settings → Runners pings each node; a red dot means the server can't reach the node's URL. Check the URL you registered and any firewall between server and node.
• playwright install --with-deps needs root on Linux; if the node isn't root, install the browser dependencies yourself first. The node start is non-fatal if that step fails.