Convex Sandbox 透過整合「just-bash」與 Convex 儲存機制

Convex Sandbox 透過整合「just-bash」與 Convex 儲存機制，實現了無需虛擬機或容器即可運作的持久化 Bash 沙盒環境。

這項技術方案展示了如何利用 Serverless 架構的特性，在不依賴傳統容器技術的情況下，建立具備狀態且可持久化的 Bash 執行環境，為 AI Agent 提供了一個輕量級的互動式沙盒解決方案。

核心執行架構
該專案的核心邏輯在於將「just-bash」（一個在 Node.js 中運行的 Bash 解釋器）封裝於 Convex 的 Action 中。其運作機制並非依賴虛擬機或容器，而是透過以下步驟實現狀態持久化：

• 懶加載檔案系統 (Lazy Filesystem Hydration)：檔案並非在執行前全部載入，而是註冊為非同步回呼。只有當指令實際讀取檔案時，才會從儲存空間提取內容，有效降低了處理大量檔案時的效能損耗。
• 檔案系統變更追蹤：透過攔截虛擬檔案系統的寫入、刪除、移動等方法，系統能精確構建執行期間的變更差異（diff），確保只有變更過的檔案會被寫回儲存空間。
• 工作目錄持久化：由於「just-bash」在每次呼叫後會重置工作目錄，系統透過在指令後附加隱藏的 pwd 指令，並從輸出中提取路徑，成功在不同指令呼叫間維持了工作目錄的狀態。

資料模型與持久化機制
為了在無狀態的 Serverless 環境中維持沙盒狀態，該專案設計了一套基於 Convex 的資料模型，確保環境的隔離性與持久性：

• 沙盒 (Sandboxes)：作為頂層隔離邊界。
• 工作階段 (Sessions)：記錄每個終端機的 sandboxId 與當前工作目錄 (cwd)。
• 檔案 (Files)：儲存虛擬檔案系統的條目，並透過 storageId 連結至 Convex 的檔案儲存服務。
• Agent 執行緒 (AgentThreads)：將 AI Agent 的對話執行緒與特定的沙盒及工作階段進行映射。

AI Agent 整合
該專案內建了對 AI Agent 的支援，透過 @convex-dev/agent 與 Vercel AI Gateway 整合，使 Agent 能夠透過工具呼叫（tool calling）直接在沙盒中執行指令。這種設計讓 Agent 能夠在對話過程中，持續進行目錄切換與檔案修改，實現了具備上下文感知能力的互動式程式開發體驗。

技術優勢與限制
這項實作提供了一種極致輕量化的沙盒選擇，特別適合需要快速部署與 AI 互動的場景：

• 無需容器：完全依賴 Convex 的資料庫、檔案儲存與 Action 功能，大幅簡化了基礎設施的複雜度。
• 狀態持久化：透過將變更寫回 Convex 儲存，實現了跨呼叫的環境持久性。
• 效能優化：利用懶加載與差異化更新，避免了全量檔案同步的開銷。