Writing a Podfile for Your Repo

A Podfile committed to your repo means every contributor, CI runner, and AI agent gets the exact same development environment. No "works on my machine," no 30-minute setup docs.

Where to put it

Place podfile.yaml at the root of your repository. Alternatively, use .podspawn/podfile.yaml if you prefer keeping it in a dotdir. Podspawn checks both locations, with the root file taking priority.

Minimal examples

base: ubuntu:24.04
packages: [go@1.24, make]
on_create: go mod download

base: ubuntu:24.04
packages: [nodejs@22]
on_create: npm install

base: ubuntu:24.04
packages: [python@3.13]
on_create: |
  pip install uv
  uv sync

This gives contributors the language toolchain and pre-downloaded dependencies. That's often enough.

A real-world example

extends: ubuntu-dev
packages:
  - go@1.24
  - make
  - protobuf-compiler

env:
  DATABASE_URL: "postgres://postgres:devpass@postgres:5432/myapp"

services:
  - name: postgres
    image: postgres:16
    ports: [5432]
    env:
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: myapp

ports:
  expose: [8080, 9090]
  strategy: auto

on_create: |
  go mod download
  go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
  make generate

on_start: |
  echo "Ready. Run 'make dev' to start the server."

Best practices

Pin package versions. go@1.24 is better than just go. Contributors should all be on the same version.

Keep it minimal. Only include what's needed to build and test. Personal preferences (editor configs, shell themes) belong in dotfiles, not the Podfile.

Use on_create for heavy setup. Dependency installation, code generation, database migrations -- anything slow goes in on_create because it only runs once when the container is first created.

Use on_start for lightweight tasks. Welcome messages, environment checks, starting background processes.

Use extends for shared bases. If your org has multiple repos with similar tooling, create a base Podfile and extend it rather than duplicating setup across repos.

Test with podspawn dev. Before committing, run podspawn dev -- make test to verify the Podfile produces a working environment.

What not to include