diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index ecdeb5e5..0e66080c 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -166,18 +166,41 @@ On first run, HAPI:
 <details>
 <summary>Environment variables</summary>
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLI_API_TOKEN` | Auto-generated | Shared secret for authentication |
-| `HAPI_API_URL` | `http://localhost:3006` | Hub URL for CLI |
-| `HAPI_LISTEN_HOST` | `127.0.0.1` | HTTP service bind address |
-| `HAPI_LISTEN_PORT` | `3006` | HTTP service port |
-| `HAPI_PUBLIC_URL` | - | Public URL for external access |
-| `HAPI_HOME` | `~/.hapi` | Config directory path |
-| `DB_PATH` | `~/.hapi/hapi.db` | Database file path |
-| `CORS_ORIGINS` | - | Allowed CORS origins |
-| `ELEVENLABS_API_KEY` | - | ElevenLabs API key for voice |
-| `ELEVENLABS_AGENT_ID` | Auto-created | Custom ElevenLabs agent ID |
+| Variable | Default | settings.json | Description |
+|----------|---------|---------------|-------------|
+| `CLI_API_TOKEN` | Auto-generated | `cliApiToken` | Shared secret for authentication |
+| `HAPI_API_URL` | `http://localhost:3006` | `apiUrl` | Hub URL for CLI connections |
+| `HAPI_LISTEN_HOST` | `127.0.0.1` | `listenHost` | Hub HTTP bind address |
+| `HAPI_LISTEN_PORT` | `3006` | `listenPort` | Hub HTTP port |
+| `HAPI_PUBLIC_URL` | - | `publicUrl` | Public URL for external access |
+| `CORS_ORIGINS` | - | `corsOrigins` | Allowed CORS origins (comma-separated) |
+| `TELEGRAM_BOT_TOKEN` | - | `telegramBotToken` | Telegram Bot API token |
+| `TELEGRAM_NOTIFICATION` | `true` | `telegramNotification` | Enable Telegram notifications |
+| `HAPI_RELAY_FORCE_TCP` | `false` | - | Force TCP mode for relay |
+| `VAPID_SUBJECT` | `mailto:admin@hapi.run` | - | Web Push contact info |
+| `HAPI_HOME` | `~/.hapi` | - | Config directory path |
+| `DB_PATH` | `~/.hapi/hapi.db` | - | Database file path |
+| `ELEVENLABS_API_KEY` | - | - | ElevenLabs API key for voice |
+| `ELEVENLABS_AGENT_ID` | Auto-created | - | Custom ElevenLabs agent ID |
+</details>
+
+<details>
+<summary>settings.json example</summary>
+
+Configuration priority: **ENV > settings.json > default**
+
+When ENV values are set and not present in settings.json, they are automatically saved.
+
+```json
+{
+  "$schema": "https://hapi.run/schemas/settings.schema.json",
+  "listenHost": "0.0.0.0",
+  "listenPort": 3006,
+  "publicUrl": "https://your-domain.com"
+}
+```
+
+JSON Schema: [settings.schema.json](https://hapi.run/schemas/settings.schema.json)
 </details>
 
 ## CLI setup
diff --git a/docs/public/schemas/settings.schema.json b/docs/public/schemas/settings.schema.json
new file mode 100644
index 00000000..b1f5556b
--- /dev/null
+++ b/docs/public/schemas/settings.schema.json
@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hapi.run/schemas/settings.schema.json",
+  "title": "HAPI Settings",
+  "description": "Configuration file for HAPI (~/.hapi/settings.json)",
+  "type": "object",
+  "properties": {
+    "cliApiToken": {
+      "type": "string",
+      "description": "Shared secret for CLI authentication. Auto-generated if not set. ENV: CLI_API_TOKEN"
+    },
+    "apiUrl": {
+      "type": "string",
+      "format": "uri",
+      "default": "http://localhost:3006",
+      "description": "Hub URL for CLI connections. ENV: HAPI_API_URL"
+    },
+    "listenHost": {
+      "type": "string",
+      "default": "127.0.0.1",
+      "description": "Hub HTTP bind address. ENV: HAPI_LISTEN_HOST"
+    },
+    "listenPort": {
+      "type": "integer",
+      "default": 3006,
+      "minimum": 1,
+      "maximum": 65535,
+      "description": "Hub HTTP port. ENV: HAPI_LISTEN_PORT"
+    },
+    "publicUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Public URL for external access (e.g., Telegram Mini App). ENV: HAPI_PUBLIC_URL"
+    },
+    "corsOrigins": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Allowed CORS origins. ENV: CORS_ORIGINS (comma-separated)"
+    },
+    "telegramBotToken": {
+      "type": "string",
+      "description": "Telegram Bot API token from @BotFather. ENV: TELEGRAM_BOT_TOKEN"
+    },
+    "telegramNotification": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable Telegram notifications. ENV: TELEGRAM_NOTIFICATION"
+    },
+    "vapidKeys": {
+      "type": "object",
+      "description": "Auto-generated Web Push VAPID keys. Do not edit manually.",
+      "properties": {
+        "publicKey": {
+          "type": "string"
+        },
+        "privateKey": {
+          "type": "string"
+        }
+      },
+      "required": ["publicKey", "privateKey"]
+    },
+    "machineId": {
+      "type": "string",
+      "description": "Auto-generated unique machine identifier. Do not edit manually."
+    },
+    "machineIdConfirmedByServer": {
+      "type": "boolean",
+      "description": "Internal flag. Do not edit manually."
+    },
+    "runnerAutoStartWhenRunningHappy": {
+      "type": "boolean",
+      "description": "Auto-start runner when running hapi command."
+    }
+  },
+  "additionalProperties": false
+}