Skip to content

Runbook: rebuild Codespace

Status: Current | Last reviewed: 2026-05-28

Throw away the current Codespace and start fresh.

When to run

  • Devcontainer is wedged and wake-up.sh won't recover it.
  • Disk is full from leftover Docker images and docker system prune isn't enough.
  • Major dependency change in setup.sh and you want a clean baseline.

Steps

  1. Save anything local that isn't committed: bash git status git stash push -u -m "pre-rebuild" git push origin <your-branch>

    Warning: git stash has lost work in conflict resolution before. Back up any uncommitted file with cp -a to /tmp/backup-<timestamp>/ before stashing. See the feedback-backup-before-stash memory note.

  2. Export a snapshot if you want the data back: bash bash .devcontainer/dev-snapshot-export.sh The snapshot lands in your remote bucket; it includes Postgres, Redis, MinIO, and Overmind state.

  3. Delete the Codespace from the GitHub Codespaces UI.

  4. Create a new Codespace on the desired branch.

  5. Wait for postCreateCommand (setup.sh) and postStartCommand (wake-up.sh) to finish. The status bar shows progress.

  6. Restore the snapshot if you saved one: bash bash .devcontainer/dev-snapshot-import.sh <snapshot-name>

  7. Restore stashed work: bash git stash pop

Smaller alternative: just rebuild the container

In VS Code: Codespaces: Rebuild Container. This re-runs postCreateCommand and postStartCommand without losing the Codespace itself or its volumes.

See also