Persistent Storage in GitHub Codespaces: Using Connected Volumes in devcontainer.json

When a GitHub Codespace restarts or is deleted the default ephemeral filesystem is destroyed without warning Any installed dependencies modified configurations or generated artifacts stored solely in the container path disappear forcing a fresh setup This concrete problem affects developers who treat Codespaces as a regular development environment rather than a disposable sandbox Connected volumes in devcontainer.json solve the problem but plan quotas and latency mean they are not a drop-in replacement for local disk

GitHubs answer is connected volumes a devcontainer.json feature that mounts a persistent storage path surviving restarts stops and even deletion Unlike the default filesystem data written to a connected volume path remains accessible across sessions In this post well configure one verify it works and review the practical limits you should know before relying on it

Configuring a connected volume

Add a volumes entry to your repositories .devcontainer/devcontainer.json The syntax maps a host path to a container path and GitHub automatically provisions the storage on first use:

{"name":"codespace","image":"microsoft/vscode-node:latest","volumes":["~/my-data:/workspace/data:cached"]}

The :cached suffix optimizes local reads when running Codespace locally but in cloud-hosted Codespaces the mount behaves as a persistent network volume The path /workspace/data inside the container is where your code can read and write files that survive a restart

Verifying persistence

1. Start a Codespace with the configured devcontainer.
2. Create a test file inside the mounted path echo test > /workspace/data/persist.txt.
3. Stop the Codespace codespace stop or the UI button.
4. Restart the Codespace codespace start or the UI.
5. Confirm that persist.txt and its contents are still present at /workspace/data.

You can also check the Codespace settings UI under the Volumes tab to view the mounted path size usage and current status This UI check is the fastest way to confirm a volume is attached without restarting

Trade-offs and plan limits

• Quota-dependent Volume size and total storage per user are bounded by your GitHub plan and organization quotas Exceeding these limits can prevent new Codespace creation
• Latency Because connected volumes back remote storage filesystem operations may be slower than a local disk especially for workloads with many small file operations
• Deletion risk Connected volumes do not survive organization-wide Codespace deletion or account removal If the Codespace is deleted manually or via policy the volumes data is lost unless exported externally

These constraints mean connected volumes are ideal for source checkouts cached build artifacts and per-session data but less suitable for long-term archives without an external backup strategy

Actionable check

Before depending on a connected volume open your Codespace settings navigate to the Volumes section and verify the path and size match your expectations Write a small test file stop and restart the Codespace and confirm persistence If your workflow requires durable storage beyond a single GitHub account pair connected volumes with an external artifact store or regular exports