podspawnBranch Workspaces
Run multiple isolated local machines from one registered project, each pinned to its own branch and host checkout
Branch workspaces let you spin up several persistent local machines from a single registered project, each backed by its own checkout under ~/.podspawn/workspaces/<name>/. The workspace survives stop and is reused on shell, so you can park a half-finished feature branch and come back to it days later.
Walkthrough
Register the project once
podspawn add-project backend --repo https://github.com/company/backendadd-project records the repo URL in ~/.podspawn/projects.yaml. You only do this once per project.
Create a branch-specific machine
podspawn create auth-fix --project backend --branch feat/auth-retry✓ Creating auth-fix (podspawn/auth-fix:podfile-...)Podspawn clones feat/auth-retry into ~/.podspawn/workspaces/auth-fix/, builds the Podfile image, mounts the checkout into the container, runs on_create once, then on_start.
Attach a shell
podspawn shell auth-fixkarthik@auth-fix:/workspace/backend$The container starts in the bind-mounted checkout. Edits inside the container are visible on the host and vice versa.
Park it
podspawn stop auth-fixThe container, network, and sidecars are removed. The host checkout and the machine row in the state DB stay.
Pick it up later
podspawn shell auth-fixshell recreates the container from the saved workspace without recloning. on_start runs again; on_create runs only if the previous initialization never finished.
Discard when done
podspawn rm auth-fixRemoves the workspace directory and the machine row. Use --force if a session is still running.
Lifecycle
create --> running --> stop --> stopped workspace --> rm
^ |
| shell |
+---------------------------+Prop
Type
Branch resolution
Switching branches in place
podspawn switch-branch auth-fix release/1.4Runs git fetch and git checkout inside the workspace without destroying the container. Use this instead of rm + create when you want to reuse the same machine for a different branch and don't need a clean slate.
Hook semantics
on_create reruns when a previous run failed before initialization completed. Keep it idempotent: re-running apt-get install, pip install, or schema migrations on an already-initialized workspace must not fail.
on_createruns once per workspace, after the clone, on the very first successful create. The completion flag is persisted on the machine row.- If
on_createexits non-zero, podspawn tears down the container but keeps the checkout on disk. The nextcreateorshellretrieson_createagainst the same workspace. on_startruns on every container start (including afterstop/shell) and is non-fatal — failures are logged and the shell still attaches.- Local
createdoes not forward an SSH agent. Hooks that need authenticated git access must use HTTPS tokens,gh auth, or another host-side credential path.
Ephemeral runs
podspawn run review --project backend --branch release/1.4run follows the same branch resolution rules but clones into a temporary ~/.podspawn/workspaces/.tmp-<name>-<unix-nano>/ workspace and removes it on disconnect. If the process is interrupted mid-clone, the .tmp-* directory may remain — it's safe to delete manually once no matching session is running.
Use run for one-shot reviews and CI-like flows where you don't need state to survive disconnect. Use create whenever you expect to come back to the same checkout.
See also
podspawn create— full flag referencepodspawn run— ephemeral counterpartpodspawn shell— reattach contract- Hooks —
on_createandon_startsemantics
How is this guide?