podspawn run

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]

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`.

Examples

# Spin up a throwaway machine
$ podspawn run scratch

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

What happens

Pulls the image if not already cached locally

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

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

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.