diff --git a/docs/getting-started/explanation/understanding-github-codespaces/index.md b/docs/getting-started/explanation/understanding-github-codespaces/index.md
index 469196908..dc71a11db 100644
--- a/docs/getting-started/explanation/understanding-github-codespaces/index.md
+++ b/docs/getting-started/explanation/understanding-github-codespaces/index.md
@@ -28,6 +28,14 @@ to work on OpenSAFELY projects.
 
 GitHub provide users with a free monthly quota of Codespaces use.
 
+These cloud-hosted virtual machines have no persistent storage,
+which is to say any data on them will be lost when the machine is deleted
+if not saved elsewhere.
+Codespaces are primarily designed for writing code
+(such as an OpenSAFELY study)
+and are tightly integrated with GitHub,
+making it easy to commit and push your work to GitHub avoiding any data loss.
+
 ## Understanding GitHub Codespaces billing
 
 GitHub gives all users a free and decent-sized monthly quota for Codespaces.
diff --git a/docs/getting-started/how-to/add-github-codespaces-to-your-project/index.md b/docs/getting-started/how-to/add-github-codespaces-to-your-project/index.md
index 28f73b636..605be3c76 100644
--- a/docs/getting-started/how-to/add-github-codespaces-to-your-project/index.md
+++ b/docs/getting-started/how-to/add-github-codespaces-to-your-project/index.md
@@ -1,5 +1,10 @@
 This page describes how to add GitHub Codespaces to your project.
 
+!!! warning
+    Codespaces are automatically deleted after a period of inactivity and any changes not pushed to the GitHub repo will be lost.
+    For the `opensafely` organization,
+    this period is 30 days.
+
 ## Does your project already have GitHub Codespaces?
 
 Newer projects already have GitHub Codespaces.