> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 環境變數

> 自託管執行階段、Relay 和桌面端的配置項參考。

## 桌面端

| 變數 | 說明 |
| - | - |
| `VIBEX_HOME` | 覆蓋執行階段 home 的基目錄。通道專屬目錄（`desktop-preview` / `desktop-rc` / `desktop-stable`）建在它下面。 |
| `VIBEX_PROVIDER_SECRET_STORE` | `keychain`（預設）或 `file`。沒有可用鑰匙串的主機需要設為 `file`。 |
| `VIBEX_DISABLE_REMOTE_CLIENT` | 設為 `1` 時強制使用本地權威執行階段，忽略已儲存的遠端憑據。 |
| `VIBEX_SSH_REMOTE_RUNTIME` | `1` 開啟 SSH/WSL 遠端執行階段入口，`0` 關閉；覆蓋開發者設定並在介面上鎖定。 |
| `VIBEX_CHANNEL` | 構建期變數，不能在執行階段覆蓋。試影像執行階段切換通道會返回 `release_channel_override_rejected`。 |

## Vibex TUI

| 變數 | 說明 |
| - | - |
| `VIBEX_HOME` | 執行階段 home；TUI 用它決定附著到哪個執行階段。 |
| `VIBEX_TUI_HOME` | 覆蓋 TUI 自己的偏好目錄。 |
| `VIBEX_THEME` | 為本次執行指定主題，不寫入偏好檔案。 |
| `VIBEX_TUI_ICONS` | 為本次執行指定圖示集。 |
| `VIBEX_TUI_KEYS` | 覆蓋鍵位檔案路徑。 |
| `VIBEX_TUI_INTERFACE` | 覆蓋 `tui-interface.json` 路徑。 |

## 電腦操作

| 變數 | 說明 |
| - | - |
| `CUA_DRIVER_RS_ENABLE_WAYLAND` | 設為 `1` 時開啟 Linux Wayland 實驗路徑。預設只看到 X11 視窗；部分合成器仍不支援後臺輸入。 |

## 無頭執行階段 `vibex-server`

### 路徑與身份

| 變數 | 預設值 | 說明 |
| - | - | - |
| `VIBEX_HOME` | `/data` | 執行階段 home：資料庫、Agent 安裝、身份金鑰。 |
| `VIBEX_DB_PATH` | `$VIBEX_HOME/vibex.db` | 權威 SQLite 路徑。 |
| `VIBEX_WORKSPACE_ROOTS` | `$VIBEX_HOME` | 逗號分隔的絕對路徑，限定客戶端可選的專案目錄。 |
| `VIBEX_APPLICATION_ID` | `dev.vibex.server` | home 鎖使用的應用身份。 |
| `VIBEX_ACQUIRE_HOME_LOCK` | `true` | 已有執行階段佔用該 home 時立即失敗。 |

### 網路與 TLS

| 變數 | 預設值 | 說明 |
| - | - | - |
| `VIBEX_BIND_ADDR` | `127.0.0.1:8765` | 閘道器監聽地址。 |
| `VIBEX_DEPLOYMENT_MODE` | `loopback` | `loopback` / `lan` / `public`。 |
| `VIBEX_TLS_MODE` | `VIBEX_DEPLOYMENT_MODE=loopback` 時為 `loopback_http`，其它模式為 `trusted_https_proxy` | 四種取值：`loopback_http`（明文 HTTP，僅迴環地址）、`trusted_https_proxy`（由反向代理終止 TLS）、`pinned_certificate`（執行階段用自簽證書終止 TLS，客戶端從連線串固定指紋）、`server_certificate`（執行階段用你提供的 PEM 終止 TLS）。展開說明見[自託管無頭執行階段](https://vibex.peatboy.com/docs/zh-TW/self-hosted-server.md#環境變數)。 |
| `VIBEX_TLS_CERT_FILE` / `VIBEX_TLS_KEY_FILE` | 未設定 | `server_certificate` 模式下必填。 |
| `VIBEX_PUBLIC_HOST` | 未設定 | 向配對客戶端通告的地址，也用於生成連線串。區域網直連時要帶埠。 |
| `VIBEX_ALLOWED_HOSTS` | `localhost,127.0.0.1,::1` | 接受的 `Host` 值，不匹配返回 `421`。 |
| `VIBEX_ALLOWED_ORIGINS` | loopback HTTP origin | 接受的瀏覽器 origin，不匹配返回 `403`。 |
| `VIBEX_TRUST_FORWARDED_HEADERS` | `false` | 只在 `trusted_https_proxy` 模式下可開啟。 |
| `VIBEX_GATEWAY_ENABLED` | `true` | Remote v2 監聽總開關。 |

### 執行階段行為

| 變數 | 預設值 | 說明 |
| - | - | - |
| `VIBEX_PROVIDER_SECRET_STORE` | `file` | 無頭主機預設寫 `provider-secrets.json`（`0600`）。可設為 `keychain`。 |
| `VIBEX_INSTALL_MANAGED_ADAPTERS` | `true` | 啟動時安裝受管 Agent 執行階段。 |
| `VIBEX_EVENT_CAPACITY` | `512` | 執行階段廣播事件積壓上限。 |
| `VIBEX_DELEGATION_SIDECAR_COMMAND` | 服務端二進位制自身 | 提供委派 MCP sidecar 的執行檔。 |
| `VIBEX_HEALTHCHECK_URL` | `http://127.0.0.1:8765/api/v2/info` | 容器健康檢查地址。 |

### 連線與限流

| 變數 | 說明 |
| - | - |
| `VIBEX_MAX_CONNECTIONS` | 併發 WebSocket 連線數。 |
| `VIBEX_MAX_IN_FLIGHT_RPCS` | 單連線併發 RPC 上限。 |
| `VIBEX_OUTBOUND_QUEUE_CAPACITY` | 單連線事件佇列上限。 |
| `VIBEX_UNAUTHENTICATED_REQUESTS_PER_WINDOW` | 未認證路由（info、claim、ws-ticket）的每對端限流。 |
| `VIBEX_AUTH_FAILURES_PER_WINDOW` | 觸發臨時封禁前的認證失敗預算。 |
| `VIBEX_RATE_LIMIT_WINDOW_MS` | 限流視窗長度。 |
| `VIBEX_MAX_TRACKED_PEERS` | 對端跟蹤表容量上限。 |

## Relay

| 變數 | 預設值 | 說明 |
| - | - | - |
| `VIBEX_RELAY_BIND_ADDR` | `127.0.0.1:9700` | 監聽地址。 |
| `VIBEX_RELAY_HOST_BIND` | — | 顯式使用宿主機網路時覆蓋繫結。 |
| `VIBEX_RELAY_SITE_ADDRESS` | — | Caddy profile 使用的公網域名。 |
| `VIBEX_RELAY_ROOM_TTL_MS` | `3600000` | 房間存活時間。 |
| `VIBEX_RELAY_BRIDGE_TIMEOUT_MS` | `30000` | 相容橋接超時。 |
| `VIBEX_RELAY_HEARTBEAT_TIMEOUT_MS` | `45000` | 心跳超時。 |
| `VIBEX_RELAY_MAX_ROOMS` | `1024` | 最大房間數。 |
| `VIBEX_RELAY_MAX_TOTAL_CONNECTIONS` | `4096` | 最大總連線數。 |
| `VIBEX_RELAY_MAX_CONNECTIONS_PER_ROOM` | `1` | 每房間 PC 連線數，**固定為 1**。 |
| `VIBEX_RELAY_MAX_DEVICES_PER_ROOM` | `8` | 每房間裝置數。 |
| `VIBEX_RELAY_MAX_BODY_BYTES` | `1048576` | 請求體上限。 |
| `VIBEX_RELAY_MAX_REQUESTS_PER_WINDOW_PER_ROOM` | `120` | 每房間每視窗請求數。 |
| `VIBEX_RELAY_MAX_QUEUE_BYTES_PER_CONNECTION` | `4194304` | 每連線佇列上限。 |
| `VIBEX_RELAY_MAX_BANDWIDTH_BYTES_PER_WINDOW` | `16777216` | 每視窗頻寬上限。 |
| `VIBEX_RELAY_PUSH_PROVIDER` | 未設定 | 可選推送提供方。 |
| `VIBEX_RELAY_PUSH_AUTH_TOKEN` | 未設定 | 推送認證令牌。 |
| `VIBEX_RELAY_PUSH_ADAPTER_URL` | 未設定 | 推送介面卡地址。 |
| `VIBEX_RELAY_PUSH_ADAPTER_AUTH_TOKEN` | 未設定 | 推送介面卡令牌。 |

## 構建期變數

這些只在從原始碼構建或打包時生效：

| 變數 | 說明 |
| - | - |
| `VIBEX_CHANNEL` | `preview` / `rc` / `stable`，決定產品身份和資料目錄。 |
| `VIBEX_MOBILE_ANDROID_TARGETS` | 空格分隔的 ABI 列表，覆蓋 Debug 預設值。 |
| `VIBEX_ANDROID_KEYSTORE_BASE64` | 釋出簽名用的 keystore。 |
| `VIBEX_ANDROID_KEYSTORE_PASSWORD` | keystore 密碼。 |
| `VIBEX_ANDROID_KEY_PASSWORD` | 金鑰密碼（可選）。 |
| `VIBEX_ANDROID_KEY_ALIAS` | 金鑰別名，預設為 `vibex`。 |
| `VIBEX_UPDATE_PUBLIC_KEY` | 更新清單驗籤公鑰。 |

> [!WARNING]
>
> 金鑰類環境變數不要寫入版本庫、診斷資料或公開 Issue。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.