Configure the worker

A worker's size is set in one file, node.yaml, in the config directory of the worker's home (~/.pidgen/config/node.yaml by default). It says how many prompt and script workers the worker may run, and how many sessions of each coding agent may run at once. Change it with pidgen-worker capacity or in an editor; either way, the running worker applies the change without a restart.

What setup writes

When the worker is set up it writes a node.yaml sized for what the machine has. On a machine where the pi and claude commands are installed and codex is not, that is:

version: 2
capacity:
  prompts: {min: 2, max: 4}   # prompt workers, shared by every coding agent
  scripts: {min: 1, max: 2}   # workers for bash: and script: steps
harnesses:                    # sessions each coding agent may run at once
  pi: {max: 2}
  claude: {max: 2}
  codex: {max: 0}             # 0, or leaving it out, switches the agent off

Each coding agent whose command is installed gets max: 2; one that is not installed gets max: 0. If no coding agent is installed, setup still writes a valid file with every agent at 0: install one, then switch it on with pidgen-worker capacity set <harness> --max 2. Setup never rewrites a node.yaml that is already there.

The worker pools

capacity.prompts sizes the pool of prompt workers, which run coding-agent steps, and capacity.scripts the pool of script workers, which run bash: and script: steps.

Key	Meaning	Allowed values
capacity.prompts.min, capacity.scripts.min	Workers kept running when nothing is waiting.	1 to 64
capacity.prompts.max, capacity.scripts.max	The most workers the pool grows to.	1 to 64, and at least min

A pool starts at min workers. While steps of its kind are waiting it adds one worker at a time, up to max, and once a worker has been idle for two minutes it is stopped again, down to min. Every coding agent shares the one prompt pool, first come, first served.

Each worker is a process on your machine, and every coding-agent session it runs uses memory and CPU besides. Size max for what the machine can run at once alongside whatever else you use it for.

The workspace worker is always exactly one and is not configurable.

Coding-agent session caps

harnesses.<harness>.max caps how many sessions of one coding agent run at once on this machine. The agents are pi, claude and codex; Coding agents and subscriptions describes them.

Key	Meaning	Allowed values
harnesses.pi.max, harnesses.claude.max, harnesses.codex.max	Sessions of that agent at once. 0, or leaving the agent out, switches it off on this machine.	0 to 64

A cap never starts a worker or holds one back for its agent: every session runs on a worker from the prompt pool. The caps may therefore add up to more than capacity.prompts.max. With the file above:

1. Two Claude Code steps arrive. They take the two prompt workers that are already running.
2. A Pi step arrives. The pool grows to three workers.
3. A third Claude Code step waits: Claude Code is at its cap of 2.
4. A second Pi step arrives. The pool grows to four, its max.
5. Anything further waits for a free worker, or for its agent to drop below its cap.

A cap lower than a provider's own limit is a good way to keep a share of a subscription for your own use of that agent.

Change the size with pidgen-worker capacity

pidgen-worker capacity show
pidgen-worker capacity set prompts --min 1 --max 6
pidgen-worker capacity set scripts --max 4
pidgen-worker capacity set claude --max 3
pidgen-worker capacity set codex --max 0

Command	What it does
pidgen-worker capacity show	Prints the digest of node.yaml as saved, beside the digest and revision the running worker has applied, any change it refused and why, and when it last told Pidgen about it. Without a running worker it prints the file alone and manager not running.
pidgen-worker capacity set prompts|scripts [--min N] [--max N]	Sets one pool's range.
pidgen-worker capacity set pi|claude|codex --max N	Sets one coding agent's session cap. --max 0 switches it off.
pidgen-worker capacity reload	Applies a change you made in an editor now rather than within the next minute.

Values are absolute, and a value you leave out keeps its current setting. set keeps the file's comments and layout, checks the whole resulting file before saving it, and refuses rather than overwrites a change someone else saved meanwhile. It prints saved, then one of:

• applied <digest> rev <n>: the running worker is using the new size.
• saved, apply pending: the worker did not answer within about 10 seconds; it applies the file on its own within a minute.
• saved; manager not running; pending: the worker is not running; it uses the file when it starts.

The commands exit 0 on success or a pending apply, 1 when the file is invalid or the change was refused (nothing is written), and 2 for a command line they do not understand. Older spellings are refused with a note saying what to use instead: default is now prompts, process is now scripts, and --enable and --disable are replaced by --max.

Edit node.yaml by hand

You can also edit the file in an editor. The running worker checks it once a minute and applies a valid change at once; run pidgen-worker capacity reload to apply it immediately. If the file you saved is invalid, the worker keeps using the last valid version and reports the problem, which pidgen-worker capacity show and pidgen-worker doctor both print with the key at fault.

Lowering a size never interrupts work: a worker that is busy finishes its step before it is stopped, and a coding agent switched off finishes the sessions it has.

A node.yaml from an older worker, with version: 1, is upgraded when the worker starts. The original is kept beside it as node.yaml.v1.bak, and nothing has to be edited by hand.

The worker policy

config/worker-policy.yaml, beside node.yaml, says how each coding agent runs on this machine: where to find its command when it is not on PATH (the cli_path setting of pi and claude), its sandbox and network settings, and which extra environment variables Claude Code may see. Setup installs it and most people never change it. It cannot switch a coding agent on or off: only node.yaml does that. An unknown key or a value out of range in it stops the worker from starting, and pidgen-worker doctor names the problem.