Coding agent 沙箱讓 agent 生成的命令與程式碼變更，能在一個受控的工作空間中執行，並可管理檔案、程序、網路存取、機密、日誌與審查構件。實際目標並非假裝任意生成的程式碼毫無風險，而是將 agent 視為一位不受信任的貢獻者，配備一台可拋棄的開發機器、明確的邊界、可觀察的執行過程，以及在進入生產環境前必須經過人工核准的流程。
Coding agent 沙箱需要隔離哪些資源
當 agent 能夠檢查倉庫、編輯檔案、執行測試、安裝相依套件，並提交修補程式時，它才會變得有用。而這些也正是讓環境變得危險的操作。一個經由提示注入的相依套件安裝、一條破壞性的 shell 命令，或是一組意外曝露的機密，都可能造成遠比錯誤文字回答更嚴重的損害。
請圍繞 agent 可觸及的資源來設計沙箱：
| 面向 | 需控制項目 | 重要性 |
|---|---|---|
| 倉庫檢出 | 分支、提交 SHA、寫入範圍、子模組、生成檔案 | 防止 agent 修改錯誤的程式碼庫，或將變更隱藏在審查路徑之外。 |
| 檔案系統 | 工作目錄根目錄、掛載的檔案、忽略路徑、輸出目錄 | 防止 agent 廣泛存取主機檔案、憑證、快取及不相關的專案。 |
| Shell 執行 | 允許的命令、工作目錄、逾時時間、輸出擷取、核准關卡 | 賦予 agent 建置與測試所需的足夠權限，同時限制高風險操作。 |
| 套件安裝 | 註冊表政策、鎖定檔案、固定版本、快取策略、安裝日誌 | 降低 agent 要求新增相依套件時供應鏈的不確定性。 |
| 網路存取 | 預設出口流量、允許清單、DNS 行為、API 目的地、套件鏡像站 | 有助於防止非預期的資料傳輸，並讓外部呼叫可受審查。 |
| 機密 | 限定範圍的憑證、短期令牌、遮罩處理、不預設提供生產金鑰 | 防止 agent 讀取或洩漏它不需要的憑證。 |
| 構件 | 測試報告、建置產出、螢幕截圖、生成檔案、日誌 | 讓審查人員能取得具體證據，而非僅依賴 agent 的摘要。 |
| 生命週期 | 暫停、恢復、快照、重設、清理、保留策略 | 讓 agent 的執行可重複且可拋棄，而不是變成難以追蹤的長期運作機器。 |
請將此表格作為設計檢查清單。無論你的沙箱是建構在容器、虛擬機器、微型 VM、受管雲端沙箱，還是內部 Runner 之上，都適用這份清單。確切的隔離層級固然重要，但圍繞該隔離層的操作控制同樣關鍵。
執行 agent 生成程式碼的參考工作流程
最安全的 coding agent 工作流程，看起來不像聊天機器人，而更像一個受控的 Pull Request 管線。
- 為任務建立一個全新的工作空間。
- 在指定的分支或提交上檢出目標倉庫。
- 賦予 agent 一個明確的任務、測試命令與檔案範圍。
- 讓 agent 檢查檔案並提出計畫。
- 自動執行低風險的唯讀命令。
- 對高風險命令要求核准或政策檢查。
- 擷取每一條命令、結束碼、標準輸出、標準錯誤、檔案寫入與生成的構件。
- 在沙箱內執行測試、型別檢查、Linter、建置或目標腳本。
- 匯出修補程式、差異比對、測試輸出與構件套件。
- 除非明確保存快照，否則在審查後重設或銷毀工作空間。
關鍵細節在於，沙箱不僅是執行程式碼的地方，它同時也是證據記錄器。審查人員應能回答以下問題：檢出了哪個倉庫、哪些內容被變更、哪些命令被執行、哪些操作失敗、哪些通過、產出了哪些檔案，以及聯絡了哪些外部資源。
對於簡單的 agent，可將其實作為一個動作佇列，並對每個動作加入政策檢查。對於功能更強大的 agent，則應維持相同的邊界，但讓控制層更加明確：一個元件決定 agent 可請求的內容，一個元件執行已核准的動作，另一個元件則記錄執行過程。
使用者任務
-> agent 提出檔案讀取、編輯與命令
-> 政策層對每個動作進行分類
-> 沙箱執行已核准的動作
-> 擷取日誌、差異比對與構件
-> 在合併或部署前由人工審查修補程式
這種分離方式可防止模型同時擔任規劃者與危險操作的最終決策者。
命令執行前的安全檢查點
從假設生成的命令可能是錯誤的、範圍過大，或受到倉庫內容影響開始。Coding agent 可能會從測試 fixture、README、Issue 內容、套件腳本或網頁中讀取惡意指令。沙箱應讓這些失敗變得可見且可控。
在執行 shell 命令之前，請定義命令分類：
| 命令類別 | 範例 | 預設政策 |
|---|---|---|
| 唯讀檢查 | pwd、ls、git status、rg、cat package.json |
通常允許並記錄。 |
| 本地驗證 | npm test、pytest、go test、cargo test |
允許，但設定逾時並擷取輸出。 |
| 建置或生成 | npm run build、程式碼生成、文件生成 |
當輸出路徑符合預期時允許。 |
| 相依套件變更 | 套件管理員安裝、鎖定檔案更新 | 需要政策檢查或核准。 |
| 網路命令 | 擷取 URL、呼叫 API、複製額外倉庫 | 需要目的地政策與記錄。 |
| 破壞性命令 | 刪除、強制重設、磁碟清理、廣泛的 chmod/chown | 封鎖或需要明確的人工核准。 |
| 機密存取 | 讀取環境變數檔案、憑證儲存庫、部署配置 | 除非任務特定且範圍受限，否則封鎖。 |
這並不要求一個完美的靜態分析器。即使簡單的控制措施也能發揮作用：工作目錄限制、明確的拒絕模式、命令逾時、輸出大小限制，以及針對會變更相依套件、觸碰機密或聯絡外部主機的命令，設立核准提示。
檔案系統邊界同樣應具體明確。僅掛載 agent 所需的倉庫與臨時目錄。避免掛載操作者的家目錄、SSH 金鑰、雲端配置、套件管理員憑證、瀏覽器設定檔或生產環境檔案。如果需要快取來提升速度，建議使用唯讀或任務專屬的快取，並設定明確的保留規則。
如何處理套件安裝與網路存取
套件安裝是 coding agent 沙箱中最困難的部分之一，因為它既實用又充滿風險。Agent 需要重現建置並執行測試，但安裝腳本可以執行程式碼、拉取傳遞性相依套件，並聯絡外部基礎設施。
對套件相關操作使用更嚴格的政策：
- 優先使用基於鎖定檔案的安裝，而非自由形式的相依套件解析。
- 記錄套件管理員命令、註冊表 URL、套件名稱、版本與鎖定檔案變更。
- 盡可能將相依套件下載路由至經核准的註冊表或鏡像站。
- 將新增相依套件視為需要審查的程式碼變更。
- 對於高風險工作流程，封鎖安裝腳本，除非專案明確需要。
- 將相依套件快取與機密及不相關的倉庫分開。
網路出口也需要同樣的處理。Coding agent 可能需要網際網路存取來取得套件註冊表、API 文件、瀏覽器檢查或整合測試，但這並不代表它需要不受限制的對外存取。
至少，請定義預設值：
| 網路問題 | 較安全的預設值 |
|---|---|
| 沙箱能否連線到網際網路？ | 否，除非任務需要。 |
| 它能否解析任意 DNS 名稱？ | 限制或記錄 DNS 與目的地主機。 |
| 它能否呼叫生產 API？ | 預設使用測試端點或模擬服務。 |
| 它能否擷取套件相依套件？ | 使用經核准的註冊表、鏡像站與鎖定檔案。 |
| 它能否上傳檔案或日誌？ | 除非目的地是預期且經審查的，否則封鎖。 |
請不要將這些控制措施描述為能夠保證絕不會發生資料外洩或相依套件遭入侵的情況。更實際的說法是：政策、隔離、記錄與審查能縮小爆炸半徑，並讓高風險行為在修補程式被信任之前更容易被偵測。
供人工審查使用的差異比對、構件與日誌
當沙箱產生的是精簡的審查套件，而非冗長的對話記錄時，人工審查的效果最佳。
針對每次執行，請擷取以下資訊：
- 用於檢出的倉庫 URL、分支與提交 SHA。
- 任務提示或 Issue 摘要。
- 讀取的檔案與寫入的檔案。
- 每一條命令、工作目錄、開始時間、結束時間、結束碼、標準輸出與標準錯誤。
- 相依套件安裝命令與鎖定檔案變更。
- 測試、Lint、型別檢查與建置結果。
- 生成的構件，例如螢幕截圖、報告、涵蓋率、二進位檔或預覽 URL。
- 以標準修補程式或 Pull Request 格式呈現的最終差異比對。
審查人員應先檢查差異比對，再使用日誌與構件來回答針對性問題。測試是否真的執行了？Agent 是否修改了請求範圍之外的檔案？它是否新增了相依套件？它是否改寫了生成的檔案？它是否呼叫了網路服務？它是否遺留了大型或敏感的構件？
對於生產團隊，請將審查關卡設為明確：
- Agent 可以提出修補程式。
- 沙箱可以執行驗證。
- 系統可以開啟 Pull Request。
- 必須由人工或經核准的政策來決定是否合併、部署，或授予更廣泛的權限。
這個邊界對於包含基礎設施、計費、驗證、部署或客戶資料路徑的倉庫尤其重要。
Novita Agent Sandbox 的定位
Novita Agent Sandbox 專為隔離、有狀態的執行環境而設計，agent 可以在其中執行程式碼、安裝相依套件、存取檔案、使用瀏覽器工作流程，並跨工作階段保留執行狀態。Agent Sandbox 概述 介紹了三個核心建構區塊：用於隔離任務執行的沙箱、用於準備環境的範本，以及用於重複使用已配置狀態的快照。
對於 coding agent 工作流程，這些原始元件自然地對應到一個受控的開發工作空間：
| Coding agent 需求 | 沙箱模式 |
|---|---|
| 從已知環境開始 | 使用包含預期執行環境與工具的範本。 |
| 在主機之外執行命令與測試 | 在沙箱專屬的檔案系統與執行環境中執行。 |
| 重複使用已準備好的設定 | 在安裝經核准的相依套件或專案工具後，儲存快照。 |
| 除錯長時間執行的 agent 工作 | 當工作流程需要連續性時，跨工作階段保留狀態。 |
| 審查後清理 | 根據保留策略重設、停止或棄用沙箱。 |
請將產品使用與安全政策分開考量。Novita Agent Sandbox 可以為執行程式碼的 agent 提供隔離的執行環境，但你的應用程式仍需定義倉庫存取、命令政策、機密範圍、網路規則、構件保留與人工核准關卡。這些選擇取決於你的威脅模型，並且應在公開生產環境使用前，由你的工程與安全負責人進行審查。
想要親手操作的開發者，也可以閱讀 Novita 指南：使用 Novita Sandbox 建置遠端程式碼執行 MCP 伺服器。如需產品文件，請從 Novita Agent Sandbox 文件 與 SDK 及 CLI 安裝指南 開始。
常見問題
Coding agent 沙箱足以讓生成的程式碼安全嗎？
不足。沙箱只是一個控制層。你仍然需要限定範圍的倉庫存取、命令政策、相依套件控制、網路限制、機密處理、日誌記錄、構件審查，以及在合併或部署前的人工核准。
Coding agent 應該有網際網路存取權限嗎？
僅在任務需要時才提供。許多程式碼審查、重構與測試工作流程，在相依套件準備好之後，可以在沒有一般網際網路存取的情況下執行。當需要網際網路存取時，請記錄目的地，並優先使用允許清單中的套件註冊表、文件網站、測試 API 或模擬服務。
Agent 應該接收生產環境的機密嗎？
預設情況下，避免將生產環境機密交給 coding agent。請使用任務專屬的限定範圍短期憑證，優先使用測試服務，對日誌進行遮罩處理，並將機密存取保留在倉庫工作空間之外，除非有經過審查的理由。
在信任 agent 的修補程式之前，應審查哪些內容？
審查差異比對、變更的相依套件、生成的檔案、命令日誌、測試結果、網路活動與任何構件。請特別注意驗證、授權、部署、計費、基礎設施、資料存取與套件管理方面的變更。
何時應重設沙箱？
在每次任務完成後重設或銷毀工作空間，除非你刻意保存快照。持久狀態對於長時間執行的工作流程很有用，但這應是一個經過深思熟慮的選擇，並附帶擁有權、保留與清理規則。
