如何自架 Dormice agent sandbox
Dormice 可在自有 Linux VPS 執行 E2B 相容的 agent sandbox。本文示範安裝、在隔離 container 執行程式碼、檢查隔離效果,並估算主機所需資源。
Dormice 是什麼,以及它不是什麼
Dormice 是自架的 agent sandbox:在你擁有的 Linux VPS 上執行一個 daemon,讓 agent 程式透過 HTTP 呼叫,在隔離的 container 內執行不受信任的程式碼。你的程式依名稱要求 sandbox,無論 sandbox 原本處於什麼狀態,都會取得同一個 sandbox,接著在其中執行命令並讀取輸出。sandbox 是由程式操作的資源,不是供你登入的機器。
這與把整台電腦交給 agent 的方式不同。供 coding agent 使用的一次性 VM 是一台可透過 SSH 登入的主機;你讓 agent 任意修改,完成後再刪除。Dormice 再往下一層:當程式已經有程式碼,且需要安全的執行位置時,Dormice 是程式呼叫的執行 API。當整台機器是工作單位時,使用一次性 VM。當單一 exec 呼叫是工作單位,且你每天想執行 100 次而不建立 100 台 VM 時,使用 Dormice。
此專案將自身定位為 E2B 相容。E2B 是代管的 sandbox 服務,許多 agent framework 已經匯入其 client library。Dormice 使用自有的 URL prefix 提供相同的 protocol,因此,對官方 e2b package 開發的應用程式,只要將目標指向你自己的主機,就能繼續執行。應用程式程式碼不需要變更。只需變更 2 個 URL 和 1 個 API key prefix。
實際上「代理程式沙盒的 SQLite」代表什麼
SQLite 是嵌入應用程式的資料庫,不是需要自行運作的服務;Dormice 直接借用了這個比喻。每台機器執行一個 daemon,以一個 SQLite 檔案保存其帳本,使用一個 TCP 埠,並在旁邊安裝小型 gateway 來提供 Web 主控台。不需要 Kubernetes,也不需要外部資料庫伺服器。daemon 會在帳本旁取得獨佔鎖定,因此同一台機器上的第二個 daemon 會拒絕啟動,而不是悄悄分割狀態。每個沙盒都位於建立它的機器上。README 現在將 fleet 描述為一個 gateway 加上其私有網路中的機器,但仍提醒:如果需要能在機器之間移動的沙盒,或跨區域的 fleet,應改用其他方案,並仔細評估。
這個概念的另一半與成本有關。託管沙盒會按存在的每一秒計費,因此託管沙盒本質上是設計成可拋棄的。Dormice 執行在你已經付費使用的硬體上,因此其沙盒是永久存在的,靜置時間越長,平均成本越低。沙盒會逐級進入閒置狀態:active、接著是 frozen,再來是 stopped,最後是 archived。任何 acquire 操作都會將它從目前所在的狀態恢復。
值得理解的是 freezing,因為這正是讓所有代理程式的沙盒永久保留仍具成本效益的原因。以下是專案自行發布的數據,測量環境是專案使用的硬體,而不是你的硬體。
此圖表背後的資料
[
{
"label": "Active, holding 1 GiB",
"resident_memory_mib": 1024,
"wake_ms": 0
},
{
"label": "Frozen",
"resident_memory_mib": 5,
"wake_ms": 50
}
]閒置沙盒原本占用 1024 MiB 記憶體,凍結後常駐記憶體會降至 5 MiB,約 50 ms 後即可恢復。程序會在原處暫停並恢復,因此長時間執行的代理程式在凍結期間仍能保留 shell 狀態與尚未完成的工作。在依此規劃容量前,請先在自己的主機上重現這項結果。
安裝前主機需要具備的條件
主機必須是 x86_64 架構的 Ubuntu 或 Debian,且安裝程式需要 root 權限。daemon 在執行期間會持續使用 root,因為它需要執行 loop mount 並寫入 cgroup。
Sandbox 會在 Docker 搭配 gVisor 的環境中執行。gVisor 是一種在容器與主機核心之間加入 userspace kernel 的容器執行環境,並提供每個 sandbox 使用的 runsc runtime。daemon 需要 Node 22 或更新版本。如果系統中的 Node 已是 22 或更新版本,安裝程式會重複使用該版本;只有在 Node 缺少或版本較舊時,安裝程式才會下載固定版本、驗證 checksum,並將其解壓縮至 /opt。
系統必須存在 swap,且 vm.swappiness 必須是 100。這不是調校建議,而是功能需求。Freeze 的運作方式是將閒置 sandbox 的記憶體移出至 swap;gVisor 會以 shared memory 保存 sandbox 記憶體,而核心在預設的 swappiness 下不會將 shared memory 移出至 swap。專案測得預設值只能回收 0 bytes,設為 100 時則可回收 99.5 percent。請確認核心實際使用的數值,因為某些 cloud image 會在你不會想到要讀取的檔案中設定 vm.swappiness = 0。
sysctl vm.swappiness
swapon --showsysctl vm.swappiness 應輸出 vm.swappiness = 100,而 swapon --show 應列出一個 swapfile。如果 swappiness 輸出 0,每次 freeze 都不會產生任何效果,導致每個閒置 sandbox 都持續佔用完整記憶體。
在 Ubuntu 上安裝 Dormice
文件記載的安裝方式,是將一個管線直接導向 bash:
curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash執行前,先下載並閱讀該檔案。此腳本會以 root 身分執行,並修改主機環境:如果尚未安裝 Docker,便會安裝 Docker;下載 gVisor 與 Caddy 並驗證 checksum;如果主機沒有 swap,便建立 swapfile;為 daemon、gateway 與 image registry 寫入 systemd 單元;以及加入防火牆規則。
curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh -o dormice-install.sh
less dormice-install.sh
sudo bash dormice-install.sh --swap-gb 8--swap-gb 設定 swapfile 大小,預設值為 16;對小型 VPS 而言,這會占用過多磁碟空間。--mirror cn 會將下載來源切換為中國大陸可連線的 mirror。重新執行安裝程式會升級程式碼並修正環境偏移,但不會輪替 API token。
程式碼會放在 /opt/dormice,設定檔會放在 /etc/dormice/env(gateway 另有 /etc/dormice/gateway.env),sandbox 資料會放在 /var/lib/dormice,而 dormice 與 dor 指令會放在 /usr/local/bin。安裝程式會在安裝期間產生 API token,並以 mode 600 寫入 /etc/dormice/env;相同的值也會寫入 gateway 的檔案。
目前沒有可供安裝的標記版本。截至 12 October 2026,repository 沒有 git tags,也沒有 GitHub releases,因此安裝程式會 clone main,你取得的是當天早上已提交的版本。因此,若要固定版本,就必須記錄實際安裝的 commit。
git -C /opt/dormice rev-parse HEAD請將該 hash 與部署備註一併保存,因為它能明確指出目前執行的程式碼。單靠它無法復原:新程序會在啟動時套用 database migrations,而升級文件指出,重新執行較舊的安裝程式不會反向移除 migration。重新啟動任何服務前,安裝程式會先將兩個 database 的 snapshot 儲存至 /var/lib/dormice/backups/,並保留最近的 3 份。這些 snapshot 是升級失敗後文件記載的復原方式,因此再次升級前,請先將最新的 snapshot 複製到主機外。
安裝程式最後會執行 dor doctor。這是唯讀的主機檢查工具,會啟動實際的 gVisor container,以確認 runtime 可正常運作,而不是只依據套件清單判斷。daemon 行為異常時,請再次執行此檢查。
sudo dor doctor
systemctl is-active dormicesystemctl is-active dormice 應輸出 active。如果輸出 failed,原因會記錄在 journalctl -u dormice -n 50;啟動失敗通常是 swap 或 gVisor 先決條件未滿足,而不是 daemon 本身的問題。
安裝程式也會在主機上安裝 Caddy,因此在判定防火牆設定完成前,請先查看目前有哪些服務正在監聽。
sudo ss -lntpdaemon 一律繫結至 127.0.0.1,設計上沒有可變更該位址的設定。只有埠號可以變更:DORMICE_PORT 的預設值為 3676。旁邊的 gateway 也遵循相同規則,繫結至 127.0.0.1:3677,埠號使用 DORMICE_GATEWAY_PORT,並刻意不提供 host 設定。從筆記型電腦連線到任一服務都必須明確操作;最簡單的方式是使用 SSH tunnel 轉送兩個埠。
ssh -L 3676:127.0.0.1:3676 -L 3677:127.0.0.1:3677 root@your-server隧道建立後,筆記型電腦上的 http://127.0.0.1:3677/console 就是由 gateway 提供的 Web console。第一次造訪時,貼上 API token 一次,以證明你是操作人員,接著設定 console username 與 password。登入後會設定有效期 7 天的 httpOnly session cookie,頁面 JavaScript 無法讀取該 cookie,console 也不會再次顯示 token。其中的 Connect 頁面會產生可直接複製貼上的 client 程式片段,並預先指向你自己的 endpoint。
建立沙箱並在其中執行程式碼
建立沙箱的操作只有一個:acquire。此操作具備冪等性,因此相同的 key 一律會回傳相同的沙箱,並視需要建立、喚醒、啟動或還原該沙箱。其他所有動詞對從未見過的 key 都會回傳 404。dor CLI 沒有 acquire 動詞,因此第一個沙箱必須透過主控台或用戶端程式庫建立。
使用主控台最快。透過 tunnel 開啟 /console,並建立名為 my-agent 的沙箱。接著即可使用 CLI 操作該沙箱。
sudo grep DORMICE_API_TOKEN /etc/dormice/env
export DORMICE_ENDPOINT=http://127.0.0.1:3676
export DORMICE_API_TOKEN=paste-the-value-here
dor sandbox ls
dor sandbox exec my-agent 'python3 --version'dor sandbox ls 會列出每個沙箱及其生命週期狀態,可用來監控沙箱從 active 變為 frozen。dor sandbox exec 會輸出 Python 3.12 版本,因為預設映像檔是 Ubuntu 24.04,且已預先安裝 Python 3.12、Node 24、git 和 ripgrep。若出現驗證錯誤,表示你複製的 token 那一行包含了變數名稱。
檔案透過 dor sandbox push my-agent ./script.py 傳送,並會放置於 /home/user/script.py;dor sandbox pull my-agent notes.txt 可將檔案取回。原生檔案動詞對單一檔案的大小上限為 16 MiB,而 E2B 檔案介面會以串流方式傳輸,唯一限制是沙箱磁碟配額。
只有銷毀操作會遺失資料。dor sandbox destroy my-agent 會移除沙箱,且具備冪等性;主要 README、內建 agent skill 和 CLI 套件 README 都以這個名稱說明該操作。即使如此,仍應在自己的建置環境中執行 dor sandbox --help,因為安裝程式會追蹤 main,而 CLI 仍持續擴充功能。
讓現有的 E2B 程式碼指向自己的伺服器
這就是值得使用的原因。npm 提供的官方 e2b package 未經修改即可與 Dormice 通訊。保持 SSH tunnel 開啟,從筆記型電腦執行以下指令,因此伺服器上不會有新的服務監聽。
npm init -y
npm i e2b tsximport { Sandbox } from 'e2b';
const sbx = await Sandbox.create({
apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
apiUrl: 'http://127.0.0.1:3676/e2b/api',
sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
});
const result = await sbx.commands.run('python3 -c "print(6 * 7)"');
console.log(result.exitCode, result.stdout);
await sbx.kill();DORMICE_API_TOKEN=paste-the-value-here npx tsx index.ts正常執行時會輸出 exit code 0 和 42。API key 是 Dormice token,前面加上 e2b_ prefix。這是相容層要求的格式。
這項相容性不是 stub。專案的 end-to-end 測試套件會透過官方 package,針對實際的 Docker 和 gVisor daemon,測試串流 stdout 與 stderr、背景指令、互動式 PTY、簽署的上傳與下載 URL、目錄監看,以及 port proxy。在遷移任何實際工作負載前,請先注意以下幾項差異:
- 不支援 template build。Template 是自行建置並使用
dor template add註冊的 docker image,Sandbox.create('name')會解析該 image。未註冊的名稱會回傳 404,不會假裝成功。 - 透過 E2B 介面建立的 sandbox 會套用實際的 deadline,因為 E2B 語意要求如此。透過原生 API 建立的 sandbox 永遠不會套用 deadline。
- 凍結的 sandbox 會保留其 process,並從中斷處繼續執行。因此,此處的 pause 和 resume 並不是你可能熟悉的 stop 和 cold start。
沙箱能阻擋什麼,以及無法阻擋什麼
gVisor 會在使用者空間攔截容器的系統呼叫,並自行處理這些呼叫,因此沙箱中的程式碼不會直接與主機 kernel 互動。在沙箱內,命令會以 user(uid 1000)執行,但該帳號可免密碼使用 sudo,因此任何提出要求的程式碼都能取得沙箱內的 root 權限。不要將 uid 視為防護措施:該專案明確指出,安全邊界是 gVisor,而不是 uid;即使沙箱中的程式碼自行提升權限,仍無法接觸主機 kernel。這可處理一般情況:產生的指令碼若執行 rm -rf /、填滿磁碟,或持續 fork 直到程序終止,受損的只會是自己的沙箱,影響也會止於沙箱內。
以下是它無法阻擋的事項。這些都由你負責。
- 沙箱具備可用的對外網路。產生的程式碼可以下載任意內容,也可以上傳它找到的任何資料。安裝程式的網路強化只涵蓋兩項措施:封鎖容器流量前往 169.254.0.0/16 的雲端 metadata service,以及 Alibaba Cloud 使用的 100.100.100.200。雲端會將執行個體憑證提供給任何能連線到該位址的程式;此外,安裝程式也會在 Docker 的
daemon.json中使用"icc": false關閉容器彼此之間的流量。其他流量一律不會封鎖。閱讀sudo iptables -S DOCKER-USER,並針對沙箱不應存取的私有網段自行加入 DROP 規則。 - Docker 會將自己的規則插入防火牆規則之前,因此即使 ufw 顯示連接埠已關閉,公開的容器連接埠仍可能回應網際網路上的請求。在此主機暴露任何服務前,請先閱讀 Docker 如何繞過 ufw 公開連接埠 以及 VPS 的 ufw 防火牆基礎。
- gVisor 是使用者空間 kernel,不是 hypervisor。這是刻意的取捨,因為凍結功能要求沙箱以程序形式執行,而要求 KVM 則會使它無法在各種環境中安裝。若你的威脅模型要求硬體虛擬化,請使用 Firecracker 類型的隔離方案,並接受其額外的維運成本。
- API token 是用戶端的完整安全邊界。任何持有
DORMICE_API_TOKEN的人,都能在這台機器上建立、讀取及刪除所有沙箱。請讓 agent 程序使用專屬的 VPS 最小權限使用者,並以保護 SSH key 的方式保護該 token。在 VPS 上安全執行 Claude Code 的做法同樣適用。
daemon 本身會以 root 身分在主機上執行。gVisor 可保護主機免受沙箱內程式碼影響,但沒有任何機制能保護主機免受 daemon 或 token 持有者影響。因此,執行 Dormice 的機器應只負責這項工作。若你的 agent 也透過 MCP(model context protocol)存取工具,基於相同原因,請將這些 MCP server 放在獨立的 VPS 上。
4 GB 和 8 GB 能容納多少個 sandbox?
會耗用記憶體的因素有兩個:主機本身的基線用量,以及目前處於喚醒狀態的每個 sandbox 工作集。先為 Ubuntu、Docker 和 daemon 保留約 1 GB,再將剩餘記憶體除以單一 sandbox 的實際用量。執行會讀取幾個檔案之 Python script 的 sandbox,通常約使用 200 到 300 MiB。執行 compiler 或完整 test suite 的 sandbox,可能超過 1 gibibyte。
此圖表背後的資料
[
{
"host": "4 GB VPS",
"active_at_512_mib": 6,
"active_at_1_gib": 3,
"frozen_on_16gb_swap": 16
},
{
"host": "8 GB VPS",
"active_at_512_mib": 14,
"active_at_1_gib": 7,
"frozen_on_16gb_swap": 16
}
]如果每個 sandbox 使用 512 MiB,4 GB VPS 一次約可讓 6 個 sandbox 保持喚醒;如果每個使用完整 1 gibibyte,則約可讓 3 個保持喚醒。8 GB VPS 對應為 14 個和 7 個。這些數字是同時執行工作的上限,屬於算術估算而非基準測試,因此請在實際負載執行時監控 free -m。
凍結的 sandbox 受 swap 限制,而不是 RAM,這正是此設計的目的。若凍結前的 sandbox 使用 1 gibibyte,凍結後大約會在 swap 中保留相同容量,幾乎不占用常駐記憶體,因此安裝程式預設的 16 GB swapfile 約可暫存 16 個 sandbox。超過此數量後,這些 sandbox 必須進入 stopped 階段,此時只占用磁碟空間。長期而言,真正的限制是磁碟:每個 sandbox 都會保留自己的檔案系統,而幾十個各自包含 node_modules 目錄的 agent,會在記憶體成為問題前就填滿小容量磁碟區。
凍結、停止、封存:生命週期設定
預設行為是在閒置 10 分鐘後凍結、3 天後停止;設定封存時,則在 7 天後封存。將 stopAfterSeconds 設為 null 可提供常駐代理程式:閒置時仍可能凍結,但不會執行 cold start。
封存為選用功能,daemon 會如實反映設定。請在主控台的設定頁面設定 S3 相容儲存區(4 個 DORMICE_S3_* 變數仍然存在,但只會作為 gateway 首次啟動時的初始值),停止的 sandbox 會使用 tar 和 zstd 封裝磁碟內容,將封裝檔傳送至 bucket,並釋放本機空間。該 bucket 可以是您在另一台自有機器上自行架設的 MinIO bucket。若未設定儲存區,sandbox 會永遠停留在 stopped 狀態;要求封存的政策會被拒絕,而不是遭到靜默忽略。還原作業會明確顯示,而不是在背景靜默執行:下一次 acquire 會立即回應 restoring 狀態與進度值,磁碟還原完成後再切換為 ready。
現在適合依賴它嗎?
直接說結論:凡是無法重建的工作,都還不適合依賴它。該 repository 建立於 8 July 2026。截至 12 October 2026,它有 1,509 顆 stars、109 個 forks,採用 Apache-2.0 授權,且完全沒有 tagged release。README 自己的狀態說明也表示,目前沒有任何內容已準備好用於 production。
這種組合形成了明確的風險。安裝程式會追蹤 main,因此程式碼可能在你使用期間變動。介面仍在定型:目前文件描述的是 daemon 前方的 gateway,具有自己的 port、configuration file 和 database。另一項風險是,這個專案成立約 3 個月,可能直接停止維護,因為授權條款沒有要求任何人持續開發。
E2B 相容性讓這項風險仍可控。你的 application 會使用一套背後有 hosted implementation 的 protocol,因此如果 Dormice 停止開發,只要修改 2 個 URL 就能繼續運作。讓 agent 使用 E2B 介面,而不是 native API,便能保留這條退路。原生的 @dormice/sdk package 目前也尚未發布到 npm,因此使用它必須從 repository 建置,這也是應先採用相容路徑的另一個理由。
請在可以承受遺失的環境中執行它。使用 script 重建 host,將 token 排除在所有 prompt 和 commit 之外,並依照自己的 backup 排程,把任何需要保留的資料從 sandbox 移出。
FAQ
Dormice 已準備好用於正式環境嗎?
還沒有,專案本身也明確如此說明。README 的狀態列指出,目前其中任何內容都尚未準備好用於正式環境。截至 12 October 2026,該 repository 約建立 3 個月,沒有 git tags,也沒有 releases,因此沒有可固定使用的版本號。安裝程式會 clone main branch,表示每次執行都會取得最新 commit。每次安裝後記錄 git -C /opt/dormice rev-parse HEAD,保留安裝程式寫入 /var/lib/dormice/backups/ 的資料庫 snapshot 副本,並將任何重要資料存放在 sandbox 外部。
Dormice 與提供一次性使用的 VM 給 agent 有何不同?
一次性 VM 是一台具備 SSH 的機器。你為單次工作階段建立它,完成後再刪除。Dormice 則是 execution API:程式先呼叫 acquire,再呼叫 exec,取得 stdout 與 exit code,中間不會建立 shell session。VM 適合需要暫時使用完整電腦的人員或 agent。Dormice 適合每天多次執行產生程式碼的應用程式,避免每次執行都處理一整台機器的設定與清理。
官方 E2B SDK 真的不需修改程式碼就能運作嗎?
可以,但需要修改設定。將 apiUrl 與 sandboxUrl 指向 daemon 上的 /e2b/api 與 /e2b/envd,並在 API key 中使用 e2b_ prefix 搭配 Dormice token。Command execution、PTY sessions、file transfer、signed URLs 與 port proxy 都已涵蓋在專案透過官方套件執行的 end-to-end suite 中。Template building 是主要缺口:e2b template build 尚未實作,因此 template 是一個由你建立,並使用 dor template add 註冊的 Docker image。
4 GB VPS 可以容納多少個 sandbox?
如果每個 sandbox 使用 512 MiB,在預留約 1 GB 給 operating system、Docker 與 daemon 後,同時保持啟用的數量約為 6;如果每個 sandbox 使用完整 1 gibibyte,則約為 3。Frozen sandbox 受到 swap 容量限制,因此安裝程式預設的 16 GB swapfile 約可停放 16 個各自曾使用 1 gibibyte 的 sandbox。請在實際負載下使用 free -m 進行測量,因為執行 test suite 的 sandbox,其使用量可能是執行小型 script 的 sandbox 的數倍。
Dormice 為什麼需要將 vm.swappiness 設為 100?
凍結 sandbox 表示將其閒置記憶體移出至 swap。gVisor 會將 sandbox 記憶體保留為 shared memory,而 Linux kernel 在預設的 swappiness 下不會置換 shared memory。因此在預設值下,凍結作業不會回收任何記憶體,sandbox 仍會持續占用完整記憶體。專案測得預設值下回收 0 bytes,在 100 下則回收 99.5 percent。請使用 sysctl vm.swappiness 檢查 effective value,不要直接讀取設定檔,因為部分 cloud image 會將值設為 0。