Ways in#

Podbench has three modes. They are not three interfaces to the same thing — each one makes a different trade against the pod it is aimed at, and the trade decides which is available to you before taste does.

	`attach`	`dev`	`hotfix`
What it does	puts a seat in the running pod	runs a sacrificial clone of it	makes an edit outlive the session
Touches the workload	no — adds a container to the pod	no — the origin is left alone	yes — needs a claim in the chart
Singleton-safe	yes	no — the clone is a second copy	yes
GitOps-safe	yes	no — refused outright	mostly (#32)
Languages	any	any, but only Python is set up for you	Python only (#34)
Survives a restart	no	no	yes
Inner loop	no	yes, ~1 s	yes, one rollout per edit
What it actually does	step by step	step by step	step by step

podbench vscode is not a fourth mode. It is attach — the same seat, the same ladder, the same pod — dressed for an editor: it sizes the pod’s memory for vscode-server, installs debugpy into the target where the target says that is the blocker, and opens VS Code on the seat. Those two mutations are why it is a verb of its own rather than a flag: the Touches the workload row above is a promise attach keeps, and choosing a verb named for the editor is how you ask to spend it. See VS Code over Remote-SSH.

The last row goes to a page per mode: every check it makes, in order, and the kubectl commands each step becomes. Anything in them you have not met before — PSA, Yama, subPath, the ambient set — is in the Glossary.

Singleton-safe#

A workload is a singleton when a second copy of it is not merely wasteful but wrong: it holds a device that accepts one connection, claims a name on the network, or takes a lock. An EPICS IOC is usually all three at once.

attach and hotfix never make a second copy — one works inside the running pod, the other restarts it in place. dev is built on a clone, so for a singleton it produces two processes competing for the same device and the same names. There is no flag for this; the clone is the mode. Use hotfix for a singleton that needs an inner loop.

GitOps-safe#

Under a controller like Argo CD with self-heal on, anything podbench writes to a git-managed object is drift and gets reverted, usually within seconds and always without telling you.

attach is clear because its mutations are pod-level — an ephemeral container and an in-place resize — and pods made by a controller are not compared against git.

dev refuses to run against a workload carrying a GitOps mark, and there is no override. The reason is --take-traffic: a Service is a tracked object straight out of git, so self-heal reverts the selector within seconds and the traffic you think you have returns to the original pod with no error anywhere. Making the dev pod itself survive is possible and was rejected — it works by hiding the pod from the controller, which turns a loud failure into a silent one and leaves the Service problem untouched. Detection looks at the workload, not the pod, because that is where the mark is; a cluster that leaves Argo’s instanceLabelKey at its default is not detected, which is the safer direction to be wrong in.

hotfix works, but records its provenance on the pod template, which self-heal strips — so the fix keeps running while hotfix status stops being able to see it (#32).

Languages#

attach is language-agnostic: it is a seat with a debugger, gdb for native code and debugpy for Python, and it needs nothing from the target but a process.

dev splits. Building the dev pod, idling the app container, the relaunch and the listening-socket check are all language-agnostic — podbench run -- <command> will start anything. What is Python-specific is dev-bootstrap, which clones, runs uv sync and does an editable install. For another language, prepare the workspace yourself and use podbench run.

hotfix is Python throughout: it reads pyvenv.cfg, mounts a claim over the application’s venv, and re-runs an editable install. Generalising it is #34.

If you only remember one thing#

Start with attach. It is safe against anything, needs nothing from the chart, and answers most questions. Reach for dev when you need a fast edit-and-rerun loop and the workload tolerates a second copy; reach for hotfix when the fix has to survive a restart, or when it needs a loop and a second copy is out of the question.