diff --git a/modus/app-manifest.mdx b/modus/app-manifest.mdx
index a9f1496c..4e7db1d6 100644
--- a/modus/app-manifest.mdx
+++ b/modus/app-manifest.mdx
@@ -115,9 +115,13 @@ connection types:
 **Don't include secrets directly in the manifest!**
 
 If your connection requires authentication, you can include _placeholders_ in
-connection properties which resolve to their respective secrets at runtime. Set
-the actual secrets via the Hypermode Console, where they're securely stored
-until needed.
+connection properties which resolve to their respective secrets at runtime.
+
+When developing locally,
+[set secrets using environment variables](#working-locally-with-secrets).
+
+When deployed on Hypermode, set the actual secrets via the Hypermode Console,
+where they're securely stored until needed.
 
 </Warning>
 
@@ -324,6 +328,49 @@ This connection type supports connecting to Dgraph databases. You can use the
   The API key for the Dgraph database.
 </ResponseField>
 
+### Working locally with secrets
+
+When you run your app locally using `modus dev`, the runtime replaces the
+placeholders of the manifest with values from environment variables defined in
+your operating system or in `.env` files.
+
+The environment variables keys must be upper case and follow the naming
+convention:
+
+`MODUS_<CONNECTION NAME>_<PLACEHOLDER>`
+
+For example, with the following manifest:
+
+```json modus.json
+{
+  "connections": {
+    "openai": {
+      "type": "http",
+      "baseUrl": "https://api.openai.com/",
+      "headers": {
+        "Authorization": "Bearer {{API_KEY}}"
+      }
+    }
+  }
+}
+```
+
+The Modus runtime substitutes `{{API_KEY}}` with the value of the environment
+variable `MODUS_OPENAI_API_KEY`
+
+An easy way to define the environment variables when working locally is to use
+the file `.env.dev.local` located in your app folder.
+
+For the previous manifest, we can set the key in the .env.dev.local file as
+follow:
+
+```text .env.dev.local
+MODUS_OPENAI_API_KEY="your openai key"
+```
+
+You should exclude `.env` files from source control. Projects created with
+`modus new` exclude these files automatically when creating your project.
+
 ## Models
 
 AI models are a core resource for inferencing. The `models` object in the app