GitHub Codespaces vs Local Dev Containers: postCreateCommand Idempotency

The postCreateCommand runs once after a Dev Container is created, before the container starts, in both GitHub Codespaces and local Docker-based Dev Containers. It is not re-run on every container start; it only executes on recreation triggered by an image or devcontainer.json change.

Because the execution context differs — cloud-managed virtual machines in Codespaces versus the developer’s machine in local Dev Containers — the same command text can yield different outcomes. Codespaces provides ephemeral storage, outbound network egress, and injected secrets, while local Dev Containers rely on the host’s network, mounted volumes, and pre-existing state. Non-idempotent network calls, external service writes, or reliance on host-path references cause divergence, and partial failures can leave the two environments in inconsistent states.

1. Make the command idempotent by checking preconditions before mutating state. Use marker files or existence checks inside the container filesystem, and exit with code 0 when the desired state is already present.
2. Prefer upserts or idempotent API calls over creates. If the command interacts with external services, implement client-side deduplication or API-level upserts to make remote writes safe to re-run.
3. Guard external dependencies as optional. If a dependency is unavailable, the command should fail gracefully (exit non-zero) rather than leaving partial state, and the container should still start.
4. Add retry with exponential backoff for transient network calls, and capture exit codes and stdout/stderr to container logs for observability in both modes.
5. Write effects atomically: write to a temporary path, then rename into the final location, to avoid partial state on interruption.

A portable verification script can be run inside the container after creation in both Codespaces and local modes to assert expected files, services, and environment variables. Re-running the postCreateCommand in a throwaway container and comparing the resulting state diff provides a mode-agnostic idempotency test.

The specific operations performed by the postCreateCommand — whether it generates local files, provisions external resources, or both — change the recommended guard strategy. Confirming whether the command mutates external services is needed for precise advice.

Do not assume postCreateCommand runs on every start; it runs on creation only, so changes made after first creation are not reapplied automatically. Network and secret availability differ between Codespaces and local; hard-coded endpoints or host-only resources will fail in one mode. Marker files stored in container layers are lost on recreation; persistence must use volume-mounted paths if state must survive rebuilds.