Cutting Codespaces Startup from Minutes to Seconds with Prebuilds

The first time a new teammate opens your monorepo in a Codespace, they wait. The devcontainer image pulls, dependencies install, post-create scripts run — and a "30-second cloud environment" turns into a three-minute coffee break. Multiply that by every codespace creation across the team, and the convenience of Codespaces starts to feel like a queue.

Codespaces prebuilds exist to remove that wait. The idea is simple: GitHub builds your devcontainer ahead of time, on a schedule or on every push, and stores the result as a template. When someone creates a codespace, they start from the prebuilt snapshot instead of building from scratch. This post covers how prebuilds actually work, how to set them up for a Node.js monorepo, and the storage trade-off you need to manage.

What a prebuild actually is

A prebuild is a cached codespace environment for a specific combination of repository, branch, devcontainer configuration, and region. GitHub runs the full creation process — building the devcontainer image, running onCreateCommand and postCreateCommand, cloning the repo — then snapshots the result. When a developer creates a codespace matching that configuration, the snapshot is restored and only a small amount of personalization (dotfiles, user settings) runs on top.

Two details matter here:

• Prebuilds are configured in the repository's Settings → Codespaces → Prebuilds page (requires admin access to the repo), not inside devcontainer.json. The devcontainer file defines what gets built; the prebuild configuration defines when GitHub builds and caches it.
• Prebuilds are region-scoped. If your team is split across regions, you need to enable prebuilds for each region you care about, or some developers still pay the full build cost.

Setting up a prebuild for a Node.js monorepo

Start with a working devcontainer. A typical monorepo setup might look like this in .devcontainer/devcontainer.json:

{
  "name": "monorepo-dev",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },
  "postCreateCommand": "npm ci --workspaces",
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

The expensive part here is npm ci --workspaces — on a large monorepo that can easily take a minute or more. That's exactly what a prebuild absorbs.

To enable the prebuild (as a repo admin, in the GitHub web UI):

1. Go to the repository's Settings → Codespaces.
2. Under Prebuilds, click Set up prebuild.
3. Choose the branch (usually your default branch), the devcontainer configuration, and the region(s).
4. Set the trigger. Every push keeps the prebuild freshest; On configuration change rebuilds only when the devcontainer or related files change, which is cheaper for active branches.
5. Optionally reduce the number of retained prebuild versions to limit storage.

GitHub runs the prebuild through Actions, so you can watch it in the repository's Actions tab — look for the "Codespaces Prebuilds" workflow run. A green run means the snapshot is ready.

Verifying the speedup

Don't take the improvement on faith — measure it. The check is straightforward:

1. Push a commit to the prebuilt branch and wait for the prebuild workflow to finish.
2. Create a new codespace from that branch via Code → Codespaces → Create codespace. Time how long it takes until the terminal is usable and npm run build (or your equivalent) works immediately.
3. Compare with a codespace created from a branch or configuration that has no prebuild.

In a ready prebuilt codespace, the creation log (visible via the Codespaces: View Creation Log command in VS Code) will show the environment being restored rather than running the full postCreateCommand. Typical results for a dependency-heavy monorepo are a drop from a few minutes to well under a minute — GitHub's own published examples cite startups around the 10-second range for prebuilt configurations, though your numbers depend on repo size and personalization steps. Run the measurement yourself; don't budget around someone else's benchmark.

The trade-off: storage and staleness

Prebuilds are not free. Each prebuild snapshot consumes storage billed against the account that owns the repository, and a busy branch with "every push" triggers plus multiple regions can accumulate snapshots quickly. Two controls keep this sane:

• Retention: limit the number of prebuild versions kept per configuration. Older versions are deleted automatically.
• Trigger choice: for branches where the devcontainer rarely changes, "on configuration change" avoids rebuilding on every commit while still giving most developers a warm start.

The second risk is staleness. A prebuild captures dependencies at build time. If package-lock.json changed after the last prebuild ran, the new codespace starts fast but with outdated dependencies — and the developer pays the update cost anyway, just less predictably. The "every push" trigger mitigates this; if you use a lazier trigger, make sure your postCreateCommand is idempotent and fast to re-run, or add a lightweight update step that only installs what changed.

You can check current consumption under your organization's or account's Billing → Codespaces usage page, and delete stale prebuilds from the repository's Codespaces settings if storage climbs unexpectedly.

Where to start

Pick your default branch, enable a prebuild for one region with the "on configuration change" trigger, and measure one codespace creation before and after. If the startup time drops meaningfully, extend to "every push" and additional regions while watching the billing page for a week. Prebuilds are one of the few developer-experience improvements where the before/after is a single stopwatch measurement — so measure it, then decide how aggressive to be.