Podfile Reference (Complete)

# Base image (required unless extends is set)
base: ubuntu:24.04

# Inherit from another Podfile
extends: ubuntu-dev  # registry name, local path, or GitHub URL

# Session name override (default: derived from directory name + hash)
name: my-project

# Packages to install
packages:
  - go@1.24
  - nodejs@22
  - ripgrep

# Default shell
shell: /bin/bash  # default

# Dotfiles repository
dotfiles:
  repo: github.com/user/dotfiles
  install: ./install.sh

# Repositories to clone inside the container
repos:
  - url: github.com/org/repo
    path: /workspace/repo
    branch: main  # default

# Environment variables
env:
  KEY: value
  DYNAMIC: "${PODSPAWN_USER}"  # expanded at runtime

# Companion services
services:
  - name: postgres
    image: postgres:16
    ports: [5432]
    env:
      POSTGRES_PASSWORD: devpass
    volumes:
      - pgdata:/var/lib/postgresql/data

# Port forwarding
ports:
  expose: [3000, 8080]
  strategy: auto  # auto | manual | expose

# Resource limits
resources:
  cpus: 2.0
  memory: 4g

# Lifecycle hooks
on_create: |    # runs once on first container start
  npm install
on_start: |     # runs every time you attach
  echo "ready"

# Additional Dockerfile RUN commands
extra_commands:
  - "apt-get install -y custom-tool"

# How the host directory is available inside the container
mount: bind  # bind | copy | none

# Session lifecycle mode
mode: grace-period  # grace-period | destroy-on-disconnect | persistent

# Mount target inside container (default: /workspace/<dirname>)
workspace: /workspace/myapp