Getting Started with podspawn dev

podspawn dev turns any directory with a podfile.yaml into a ready-to-use containerized dev environment. One command, no manual setup.

The flow

git clone github.com/yourorg/yourproject
cd yourproject

podspawn dev

Podspawn reads the Podfile, builds a cached image, starts companion services, bind-mounts your code, and drops you into a shell.

You're inside the container with all tools, services, and your code at /workspace. When you're done, exit the shell or run podspawn down.

Find Podfile -- looks for .podspawn/podfile.yaml, then podfile.yaml, then falls back to .devcontainer/devcontainer.json

Resolve extends -- if the Podfile uses extends:, the base is loaded and merged

Build image -- a Docker image is built from the merged Podfile (cached by content hash, so rebuilds only happen when the Podfile changes)

Start services -- companion containers (databases, caches) are created on a shared network

Mount workspace -- your local directory is bind-mounted into the container at /workspace/<dirname>

Run hooks -- on_create runs once on first start, on_start runs on every attach

Open shell -- you're dropped into the container's shell, in your workspace directory

Instead of an interactive shell, pass a command after --:

podspawn dev -- make test
podspawn dev -- go build ./...
podspawn dev -- npm run lint

The command runs inside the Podfile environment and exits.

Flag	Type	Description
`--ephemeral`	boolean	Destroy container on exit instead of keeping it alive
`--dotfiles`	boolean	Apply your personal dotfiles from `~/.podspawn/config.yaml`
`--name <name>`	string	Override the session name (default: derived from directory)
`--fresh`	boolean	Destroy any existing session and start clean
`--ports 9090,9091`	string	Forward additional ports beyond what the Podfile declares
`--podfile <path>`	string	Use a specific Podfile instead of auto-detecting

If no Podfile exists, run podspawn init to scaffold one:

podspawn init
# Detected: Go project (go.mod found)
# Base image? [ubuntu:24.04]
# ...
# Created podfile.yaml

See podspawn init for details.