podspawn run

Create and attach to an ephemeral machine, optionally from a registered project branch

Creates an ephemeral machine, attaches to it, and destroys it when you disconnect. The podspawn equivalent of docker run --rm.

For persistent machines that survive disconnects, use podspawn create instead.

Usage

podspawn run <name> [--image IMAGE]
podspawn run <name> --project <registered-project> [--branch <git-branch>]

Arguments

Argument	Required	Description
`name`	Yes	Name for the machine. Exists only for the duration of the session.

Flags

Flag	Default	Description
`--image`	(from config)	Container image to use. Falls back to `defaults.image` in config, which defaults to `ubuntu:24.04`.
`--project`	—	Registered project to clone into a temporary workspace before starting the machine.
`--branch`	—	Git branch for project-backed runs. Uses `--branch` > Podfile `branch:` > repo default branch. Requires `--project`.

Examples

# Spin up a throwaway machine
$ podspawn run scratch

# Use a specific image
$ podspawn run test --image node:22

# Review a branch in a fully disposable workspace
$ podspawn run review --project backend --branch release/1.4

What happens

If --project is set, clones the repo into a temporary workspace under ~/.podspawn/workspaces/.tmp-<name>-<unix-nano>/

Reads the Podfile from that clone, builds or reuses the image, and bind-mounts the checkout into the container

Creates a container with a non-root user (UID 1000, home at /home/<username>, passwordless sudo)

Attaches an interactive shell as that user

When you disconnect (exit the shell or close the terminal), the container is destroyed

If this was a project-backed run, the temporary workspace is removed too

If the process is interrupted mid-run or mid-clone, podspawn may leave a .tmp-* workspace behind. Those directories are safe to remove manually once you confirm no matching session is still running.

No state is persisted after disconnect. If you need a machine that survives disconnects, use podspawn create instead.

Destroy-on-disconnect

The container lifecycle is tied to the session, not the TCP connection. If your network drops momentarily, podspawn does not immediately kill the container. The destroy happens when the session ends, which is when the shell process inside the container exits.

In server mode, podspawn spawn uses the same destroy-on-disconnect logic when configured.