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]
podspawn create <name> --project <registered-project> [--branch <git-branch>]

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)

# Register the project once
$ podspawn add-project backend --repo https://github.com/company/backend

# Create a persistent machine from a feature branch
$ podspawn create auth-fix --project backend --branch feat/auth-retry
✓ Creating auth-fix (podspawn/auth-fix:podfile-...)

What happens

If --project is set, resolves the branch and clones the repo into ~/.podspawn/workspaces/<name>/

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

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)

Runs on_create once for a new workspace, then on_start

Registers the running session in the state database and, for project-backed machines, stores persistent machine metadata for later restarts

If on_create fails for a local project-backed machine, podspawn removes the failed container but keeps the checkout on disk so you can inspect and retry it. The next podspawn create <name> or podspawn shell <name> retries on_create, so the hook needs to be idempotent.

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.

For project-backed machines, podspawn stop <name> removes the container, network, and sidecars but keeps the host checkout and machine metadata. podspawn shell <name> recreates the container from the saved workspace without recloning. It reruns on_create only if the workspace never reached the initialized state.

Lifecycle

create  -->  running  -->  stop  -->  stopped workspace
                ^                           |
                |    shell / create         |
                +---------------------------+

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