Remove a worker

Removing a worker takes it out of your Account for good: Pidgen stops sending it work, its credential stops working, and, if it is still connected, it deletes the repository clones and workspaces it kept on the machine. This page says what each step does, in the order that leaves the machine clean.

If you only want the worker to stop for a while, you do not need to remove it: stop it, and start it again later (see Stop the worker for a while).

Stop the worker for a while

Stopping is not removing. A stopped worker keeps its credential, its clones and its workspaces, and picks up where it left off when it starts again.

A stop is a planned stop: the worker stops taking work, interrupts the steps it is running, hands them back to Pidgen so another worker can run them, and exits. It takes up to two minutes. Stop the worker the way it was started:

How the worker runs	Stop it with
Started by the Pidgen CLI	The CLI; see Workers.
A systemd user service	systemctl --user stop pidgen-worker; see Run the worker as a service.
A launchd agent	launchctl bootout gui/$(id -u)/ai.pidgen.worker; see Run the worker as a service.
A container	docker stop with a two-minute timeout; see In a container.

Do not kill the worker with kill -9: that skips the hand-back, and its steps wait until their leases run out (see What a hard kill skips).

A run tied to this machine waits while the worker is stopped. If it must go on elsewhere, see A run is stranded on a worker that is gone.

Remove the worker from your Account

Remove the worker in Pidgen, from your Account's list of workers, while the worker is still running. Removing it:

1. Revokes its credential. Within about 15 seconds the worker's connection to Pidgen is closed, the worker hands the steps it is running back to Pidgen, and it stops. It does not try to reconnect: a revoked credential is the one disconnection it treats as final, and it logs worker node credential revoked by the authority.
2. Asks the worker to delete its files. While the worker is still connected, Pidgen sends it one request to delete every workspace and every repository clone it holds. See What happens to its files.

A removed worker cannot be brought back. To use the machine again, set it up again with the Pidgen CLI (Install a worker); it becomes a new worker with a new credential.

Revoke a credential without waiting

Revoking a worker's credential is what removing it does first, and it is also the step to take on its own when a machine is lost, or when its worker.env may have been seen by someone else. A revoked worker stops within one connection check, wherever it is, and can never connect with that credential again. Pidgen keeps a revoked worker on its list as a record of which machine held which credential.

A revoked worker that cannot be reached deletes nothing: its files stay on that machine.

What happens to its files

When the worker receives the delete request, it removes, as far as it can:

• every workspace under workspaces/ in its home, running each project's teardown hook first, as it does when a single workspace is torn down; and
• every repository clone under repos/.

A worker is enrolled in one Account, so everything in those two directories belongs to that Account; the worker removes what is on its disk, including any workspace Pidgen never recorded. Nothing outside the home is ever touched. A symbolic link is removed as a link and never followed, and if workspaces/ or repos/ is itself a link the worker refuses the request and removes nothing.

If something cannot be removed, the request fails in Pidgen and names every path left behind and why.

Everything else in the home stays:

Path under the home	After removal
workspaces/, repos/	Deleted, if the worker was connected when it was removed.
worker.env	Kept. Its credential no longer works.
config/node.yaml, config/worker-policy.yaml	Kept.
logs/	Kept, so you can still read what the worker did.
spool/, staging/	Kept. Anything still in them is never sent.

Outside the home, nothing changes: your coding agents stay installed and logged in, and the worker program stays installed until you uninstall it.

Stop the service from starting it again

A removed worker stops by itself. If a service manager runs it, turn the service off as well; otherwise the service starts the worker again at the next boot, and the worker fails to connect with its revoked credential and is restarted again and again.

On Linux, under systemd:

systemctl --user disable --now pidgen-worker
rm ~/.config/systemd/user/pidgen-worker.service
systemctl --user daemon-reload

On macOS, under launchd:

launchctl bootout gui/$(id -u)/ai.pidgen.worker
rm ~/Library/LaunchAgents/ai.pidgen.worker.plist

In a container, remove the container and, once you have checked what is in it, its volume.

Clean up the machine

Check that the worker has stopped and that its clones and workspaces are gone:

pgrep -af pidgen-worker
ls ~/.pidgen/workspaces ~/.pidgen/repos

pgrep should print nothing, and both directories should be empty.

If the worker was offline when you removed it, no delete request reached it and its files are still there. Make sure the worker is stopped, then delete the two directories yourself:

rm -rf ~/.pidgen/workspaces ~/.pidgen/repos

To remove everything, delete the whole home once you no longer need its logs, and uninstall the worker program the way the Pidgen CLI installed it (see Workers):

rm -rf ~/.pidgen

If your setup chose another home, use that directory instead of ~/.pidgen in the commands above.