podspawn create

Creates a persistent named machine. The container stays alive until you explicitly stop it with podspawn stop.

Usage

podspawn create <name> [--image IMAGE]

Arguments

Argument	Required	Description
`name`	Yes	Name for the machine. Used to reference it in other commands.

Examples

# Create a machine with the default image
$ podspawn create dev
✓ Creating dev (ubuntu:24.04)

# Create a machine with a specific image
$ podspawn create dev --image alpine:3.20
✓ Creating dev (alpine:3.20)

What happens

Pulls the image if not already cached locally

Creates a container with sleep infinity as the entrypoint to keep it alive

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

Registers the machine in the state database

The container runs as your OS username, not root. The shell prompt shows username@machinename (e.g., karthik@dev:~$).

The machine keeps running until you stop it. An idle machine uses negligible resources (~0% CPU, 5-15 MB memory). Attach to it with podspawn shell, or list your machines with podspawn list. See Session Lifecycle for details on idle resource cost.

Lifecycle

create  -->  running  -->  stop  -->  gone
                ^                      |
                |    start (future)    |
                +----------------------+

Unlike podspawn run, created machines survive disconnects. They are not ephemeral.