Tự host Dormice cho sandbox của agent trên VPS

Dormice là gì và không phải là gì

Dormice là một agent sandbox tự host: một daemon chạy trên Linux VPS do bạn sở hữu. Code của agent gọi daemon này qua HTTP để chạy code không đáng tin cậy bên trong một container cô lập. Chương trình của bạn yêu cầu sandbox theo tên, luôn nhận lại cùng sandbox đó bất kể trước đó sandbox đang ở trạng thái nào, chạy một command bên trong sandbox rồi đọc output. Sandbox là một tài nguyên được điều khiển bằng code, không phải một máy để bạn đăng nhập.

Cách này khác với việc cấp cho agent cả một máy tính. Một VM tạm thời cho coding agent là một máy bạn SSH vào, cho agent tùy ý làm hỏng rồi xóa đi. Dormice nằm ở tầng thấp hơn một cấp: đây là execution API mà chương trình của bạn gọi khi đã có code và cần một nơi an toàn để chạy code đó. Dùng VM tạm thời khi cả một máy là đơn vị công việc. Dùng Dormice khi một lần gọi exec là đơn vị công việc và bạn muốn chạy một trăm lần mỗi ngày mà không cần một trăm VM.

Dự án tự gọi là tương thích với E2B. E2B là một dịch vụ sandbox được host sẵn, có client library được nhiều framework agent import. Dormice cung cấp cùng protocol đó dưới các URL prefix riêng, vì vậy ứng dụng được viết cho package e2b chính thức vẫn tiếp tục chạy khi bạn trỏ ứng dụng đến máy của mình. Code ứng dụng không thay đổi. Chỉ cần thay đổi hai URL và một API key prefix.

"SQLite của agent sandbox" nghĩa là gì trong thực tế

SQLite là database được nhúng vào ứng dụng thay vì một service mà bạn phải vận hành, và Dormice áp dụng trực tiếp cách so sánh đó. Một daemon, một file SQLite cho ledger, một cổng TCP. Không Kubernetes, không database riêng, không scheduler. Daemon tạo lock bên cạnh ledger và từ chối khởi động khi ledger của nó không thể thuộc về máy mà nó phát hiện, nhờ đó split brain không thể âm thầm xảy ra. Thiết kế này dành cho một máy. Nếu cần fleet trên nhiều host, README nói rõ rằng bạn nên chọn công cụ khác, và bạn nên làm theo.

Nửa còn lại của ý tưởng liên quan đến chi phí. Hosted sandbox tính phí cho từng giây tồn tại, nên hosted sandbox được thiết kế để có thể loại bỏ. Dormice chạy trên phần cứng mà bạn đã trả chi phí, nên sandbox của nó tồn tại lâu dài và càng rẻ hơn khi đứng yên lâu hơn. Sandbox hạ trạng thái từng bậc một: active, rồi frozen, rồi stopped, rồi archived. Mỗi lần acquire sẽ đưa nó trở lại từ bậc mà nó đã đạt tới.

Freezing là phần đáng tìm hiểu, vì đây là yếu tố giúp duy trì sandbox của mọi agent vĩnh viễn với chi phí hợp lý. Đây là các số liệu do dự án công bố, được đo trên phần cứng của dự án chứ không phải của bạn.

[
  {
    "label": "Active, holding 1 GiB",
    "resident_memory_mib": 1024,
    "wake_ms": 0
  },
  {
    "label": "Frozen",
    "resident_memory_mib": 5,
    "wake_ms": 50
  }
]

Một sandbox idle đang dùng 1024 MiB memory sẽ giảm xuống còn 5 MiB resident sau khi frozen, và trở lại sau khoảng 50 ms. Các process được suspend rồi resume tại chỗ, nên agent chạy lâu dài vẫn giữ shell state và phần việc đang làm dở qua mỗi lần freeze. Hãy tái hiện trên host của bạn trước khi dựa vào con số này để tính capacity.

Các yêu cầu đối với host trước khi cài đặt

Host phải chạy Ubuntu hoặc Debian trên x86_64 và installer cần root. Daemon vẫn chạy dưới root vì nó thực hiện loop mount và ghi vào cgroups.

Sandbox chạy trong Docker với gVisor (một container runtime đặt kernel userspace ở giữa container và kernel của host). Thành phần này cung cấp runtime runsc mà mỗi sandbox sử dụng. Daemon chạy bằng Node 22 trở lên. Installer có sẵn bản Node riêng nên không thay đổi Node trên hệ thống của bạn.

Phải có swap và vm.swappiness phải là 100. Đây không phải khuyến nghị tinh chỉnh mà là yêu cầu chức năng. Cơ chế đóng băng hoạt động bằng cách đẩy bộ nhớ của sandbox không hoạt động ra swap. gVisor lưu bộ nhớ sandbox dưới dạng shared memory, còn kernel sẽ không swap shared memory với giá trị swappiness mặc định. Dự án đo được 0 byte được thu hồi ở giá trị mặc định và 99.5 phần trăm được thu hồi khi đặt giá trị là 100. Hãy kiểm tra giá trị kernel thực sự đang dùng, vì một số cloud image đặt vm.swappiness = 0 trong một file mà bạn sẽ không nghĩ đến việc đọc.

sysctl vm.swappiness
swapon --show

sysctl vm.swappiness phải in ra vm.swappiness = 100, còn swapon --show phải liệt kê một swapfile. Nếu swappiness in ra 0, mọi lần đóng băng đều không có tác dụng và bạn vẫn phải trả toàn bộ chi phí bộ nhớ cho từng sandbox không hoạt động.

Cài đặt Dormice trên Ubuntu

Cách cài đặt được tài liệu hóa là pipe trực tiếp vào bash:

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash

Hãy tải script về và đọc trước khi chạy. Script này chạy với quyền root và thay đổi host của bạn: cài Docker nếu chưa có, tải gVisor và Caddy kèm kiểm tra checksum, tạo swapfile, ghi các systemd unit và thêm firewall rule.

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 đặt kích thước swapfile và mặc định là 16, chiếm khá nhiều dung lượng đĩa trên một VPS nhỏ. --mirror cn chuyển các lượt tải sang mirror có thể truy cập từ Trung Quốc đại lục. Chạy lại installer sẽ nâng cấp code và sửa các thay đổi lệch cấu hình, nhưng không bao giờ rotate API token của bạn.

Code được đặt trong /opt/dormice, configuration trong /etc/dormice/env, sandbox data trong /var/lib/dormice, còn các command dormice và dor nằm trong /usr/local/bin. Installer tạo API token trong quá trình cài đặt và ghi token vào /etc/dormice/env với mode 600.

Không có tagged release để cài đặt cố định. Tính đến ngày 4 August 2026, repository không có git tag và cũng không có GitHub release, nên installer clone main và bạn sẽ nhận đúng những thay đổi được đưa vào repository trong buổi sáng hôm đó. Vì vậy, pin version nghĩa là ghi lại commit thực tế đã cài đặt.

git -C /opt/dormice rev-parse HEAD

Hãy lưu hash đó cùng với ghi chú deploy. Khi một lần upgrade làm hỏng hệ thống, commit đó là cách duy nhất để quay lại, vì không có version number để yêu cầu.

Installer kết thúc bằng cách chạy dor doctor. Đây là host check chỉ đọc, khởi động các gVisor container thật để xác nhận runtime hoạt động thay vì chỉ dựa vào danh sách package. Hãy chạy lại lệnh này mỗi khi daemon hoạt động bất thường.

sudo dor doctor
systemctl is-active dormice

systemctl is-active dormice phải in ra active. Nếu in ra failed, journalctl -u dormice -n 50 chứa nguyên nhân. Lỗi khởi động thường nằm ở prerequisite của swap hoặc gVisor, không phải ở chính daemon.

Installer cũng cài Caddy trên máy, vì vậy hãy kiểm tra các service đang listen trước khi kết luận firewall đã được cấu hình xong.

sudo ss -lntp

Daemon bind vào 127.0.0.1:3676 và không có setting để thay đổi điều này, theo thiết kế. Truy cập daemon từ laptop là một hành động có chủ đích; cách đơn giản và ít tốn công nhất là dùng SSH tunnel.

ssh -L 3676:127.0.0.1:3676 root@your-server

Khi tunnel đã mở, http://127.0.0.1:3676/console trên laptop là web console. Đăng nhập bằng token một lần; sau đó token trở thành httpOnly session cookie, nên bản thân token không bao giờ được lưu ở nơi page có thể đọc. Trang Connect in sẵn các client snippet có thể copy và paste, đã trỏ đến endpoint của chính bạn.

Tạo sandbox và chạy mã trong đó

Một thao tác tạo sandbox: acquire. Thao tác này idempotent, nên cùng một key luôn trả về cùng một sandbox; hệ thống sẽ tạo, đánh thức, khởi động hoặc khôi phục sandbox đó khi cần. Mọi verb khác đều trả về 404 với key mà hệ thống chưa từng thấy. CLI dor không có verb acquire, nên sandbox đầu tiên của bạn phải được tạo từ console hoặc client library.

Dùng route của console là nhanh nhất. Mở /console qua tunnel và tạo một sandbox có tên my-agent. Sau đó CLI sẽ làm việc trên sandbox này.

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 liệt kê từng sandbox cùng trạng thái vòng đời. Bạn có thể dùng lệnh này để monitor một sandbox chuyển từ active sang frozen. dor sandbox exec in ra phiên bản Python 3.12, vì image mặc định là Ubuntu 24.04, đã cài sẵn Python 3.12, Node 24, git và ripgrep. Nếu gặp lỗi xác thực, có thể dòng token bạn sao chép đã bao gồm cả tên biến.

Dùng dor sandbox push my-agent ./script.py để chuyển file; file sẽ được đặt tại /home/user/script.py. dor sandbox pull my-agent notes.txt đưa file trở lại. Các file verb native giới hạn mỗi file ở 16 MiB, còn file surface của E2B hỗ trợ stream nên quota ổ đĩa của sandbox là giới hạn duy nhất.

Destroy là verb duy nhất làm mất dữ liệu. Đây cũng là một ví dụ điển hình cho thấy project còn cũ: README chính và agent skill đi kèm đều ghi dor sandbox destroy <key>, trong khi README của CLI package ghi dor sandbox release <key>. Hãy chạy dor sandbox --help trên bản build của chính bạn và coi kết quả đó là chuẩn.

Trỏ code E2B hiện có của bạn vào máy chủ riêng

Đây là lý do bạn cần quan tâm. Package e2b chính thức trên npm, không chỉnh sửa, sẽ giao tiếp với Dormice. Chạy đoạn này từ laptop khi SSH tunnel đang mở, vì vậy không có listener mới nào trên server.

npm init -y
npm i e2b tsx

import { 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

Lần chạy thành công sẽ in mã thoát 0 và 42. API key là token Dormice của bạn, có thêm tiền tố e2b_ ở phía trước. Đây là định dạng mà compatibility layer yêu cầu.

Tính tương thích này không phải stub. Bộ end-to-end của dự án kiểm thử stdout và stderr dạng streaming, lệnh chạy nền, PTY tương tác, URL upload và download có chữ ký, theo dõi thư mục và port proxy thông qua package chính thức, kết nối đến Docker và daemon gVisor thực tế. Trước khi migrate hệ thống thực, bạn cần lưu ý một số điểm khác biệt:

• Template build chưa được triển khai. Template là một Docker image do bạn tự build và đăng ký bằng dor template add, còn Sandbox.create('name') sẽ resolve image đó. Tên chưa đăng ký sẽ trả về 404 thay vì giả lập như thể nó tồn tại.
• Sandbox được tạo qua giao diện E2B sẽ có deadline thực, vì semantics của E2B yêu cầu điều này. Deadline không bao giờ được áp dụng cho sandbox được tạo qua native API.
• Sandbox bị freeze vẫn giữ các process và resume chúng giữa chừng. Vì vậy, pause và resume ở đây không phải là stop rồi cold start như bạn có thể đã quen.

Sandbox ngăn được gì và không ngăn được gì

gVisor chặn các system call của container trong userspace rồi tự xử lý chúng, nên code trong sandbox không giao tiếp trực tiếp với kernel của host. Bên trong sandbox, mọi thứ chạy dưới user không có đặc quyền, uid 1000. Kết hợp này xử lý được các trường hợp thông thường: script được sinh ra chạy rm -rf /, làm đầy disk hoặc fork liên tục cho đến khi có tiến trình chết sẽ chỉ làm hỏng sandbox của chính nó rồi dừng ở đó.

Dưới đây là những việc sandbox không ngăn được. Bạn phải tự xử lý từng việc.

• Sandbox có network outbound đang hoạt động. Code được sinh ra có thể tải bất kỳ thứ gì và gửi đi bất kỳ dữ liệu nào nó tìm thấy. Network hardening của installer xử lý 2 việc cụ thể: chặn traffic từ container đến cloud metadata service tại 169.254.0.0/16, nơi cloud cung cấp credentials của instance cho mọi đối tượng truy cập được, và tắt traffic giữa các container bằng "icc": false trong daemon.json của Docker. Không có lưu lượng nào khác bị chặn. Đọc sudo iptables -S DOCKER-USER rồi tự thêm các rule DROP cho những private range mà sandbox không có lý do gì để truy cập.
• Docker chèn rule của nó lên trước firewall của bạn, nên một port của container đã publish vẫn có thể nhận kết nối từ Internet dù ufw báo port đó đã đóng. Đọc cách Docker publish port vượt qua ufw và kiến thức cơ bản về ufw firewall cho VPS trước khi expose bất kỳ thứ gì trên host này.
• gVisor là một kernel trong userspace, không phải hypervisor. Đây là một đánh đổi có chủ đích, vì cơ chế freeze yêu cầu sandbox phải là process, còn việc yêu cầu KVM sẽ khiến hệ thống không thể cài đặt ở mọi nơi. Nếu threat model của bạn yêu cầu hardware virtualisation, hãy dùng cơ chế isolation cấp Firecracker và chấp nhận chi phí vận hành đi kèm.
• API token là toàn bộ security boundary ở phía client. Bất kỳ đối tượng nào giữ DORMICE_API_TOKEN đều có thể tạo, đọc và hủy mọi sandbox trên máy. Cho agent process dùng riêng user có quyền tối thiểu trên VPS và bảo vệ token như bảo vệ một SSH key. Các nguyên tắc trong chạy Claude Code an toàn trên VPS có thể áp dụng trực tiếp.

Daemon tự chạy dưới quyền root trên host của bạn. gVisor bảo vệ host khỏi code bên trong sandbox, nhưng không có gì bảo vệ host khỏi daemon hoặc người đang giữ token của daemon. Vì vậy, máy chạy Dormice nên là máy chỉ chạy riêng Dormice. Nếu agent của bạn cũng truy cập các tool qua MCP (model context protocol), hãy đặt các MCP server trên một VPS riêng vì cùng lý do.

Có bao nhiêu sandbox có thể chạy trên 4 GB và 8 GB?

Có 2 yếu tố tiêu tốn memory: mức sử dụng cơ bản của host và working set của từng sandbox đang hoạt động. Dành khoảng 1 GB cho Ubuntu, Docker và daemon, rồi chia phần còn lại cho mức memory mà sandbox thực tế sử dụng. Sandbox chạy một Python script để đọc vài file thường dùng khoảng 200 đến 300 MiB. Sandbox chạy compiler hoặc toàn bộ test suite có thể vượt quá 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
  }
]

VPS 4 GB có thể chạy đồng thời khoảng 6 sandbox nếu mỗi sandbox dùng 512 MiB, hoặc 3 nếu mỗi sandbox dùng đủ 1 gibibyte. VPS 8 GB tăng các con số này lên 14 và 7. Đây là giới hạn cho công việc chạy đồng thời, được tính bằng số học chứ không phải benchmark, nên hãy theo dõi free -m trong khi workload thực tế của bạn đang chạy.

Số sandbox bị đóng băng bị giới hạn bởi swap thay vì RAM. Đây là mục đích chính của thiết kế này. Sandbox bị đóng băng từng giữ 1 gibibyte sẽ vẫn chiếm khoảng chừng đó trong swap và gần như không chiếm resident memory, nên swapfile mặc định 16 GB của trình cài đặt có thể chứa khoảng 16 sandbox như vậy. Sau mức đó, sandbox cần chuyển sang trạng thái stopped, khi đó chỉ còn tốn disk. Disk mới là giới hạn thực tế về lâu dài: mỗi sandbox giữ filesystem riêng, và vài chục agent, mỗi agent có một thư mục node_modules, sẽ làm đầy volume nhỏ từ lâu trước khi memory trở thành vấn đề.

Đóng băng, dừng, lưu trữ: các thiết lập vòng đời

Mặc định, sandbox sẽ đóng băng sau 10 phút không hoạt động, dừng sau 3 ngày và được lưu trữ sau 7 ngày nếu đã cấu hình lưu trữ. Đặt stopAfterSeconds thành null để có một agent thường trú: agent có thể đóng băng khi không hoạt động và không bao giờ phải cold start.

Lưu trữ là tùy chọn và daemon thể hiện rõ trạng thái này. Đặt 4 biến DORMICE_S3_*, rồi disk của sandbox đã dừng sẽ được đóng gói bằng tar và zstd, tải lên bất kỳ bucket tương thích với S3 nào và giải phóng dung lượng cục bộ. Bucket đó có thể là một MinIO bucket do bạn tự host trên một máy khác của bạn. Nếu không đặt các biến này, sandbox sẽ giữ nguyên ở trạng thái stopped mãi mãi; policy yêu cầu lưu trữ sẽ bị từ chối thay vì bị bỏ qua âm thầm. Quá trình restore cũng hiển thị rõ ràng thay vì diễn ra âm thầm: lần acquire tiếp theo trả về ngay trạng thái restoring cùng giá trị tiến độ, sau đó chuyển sang ready khi disk được khôi phục.

Bạn có nên phụ thuộc vào nó ngay lúc này không?

Nói thẳng: chưa nên dùng cho bất kỳ thứ gì mà bạn không thể dựng lại. Commit đầu tiên trong repository có ngày 8 July 2026. Tính đến 4 August 2026, repository có 446 stars, 37 forks, giấy phép Apache-2.0 và hoàn toàn chưa có release được tag. Dòng trạng thái trong chính README cũng nói rằng chưa có gì sẵn sàng cho production.

Tổ hợp này tạo ra một dạng rủi ro cụ thể. Code có thể thay đổi trong lúc bạn đang sử dụng, vì installer theo dõi main. Interface vẫn đang ổn định dần. Đây chính là lý do verb delete có hai tên khác nhau trong hai file thuộc cùng một repository. Một project mới được 4 tuần cũng có thể dừng hoạt động, vì không có điều khoản nào trong giấy phép buộc bất kỳ ai phải tiếp tục duy trì nó.

Điểm khiến rủi ro này vẫn có thể kiểm soát là khả năng tương thích với E2B. Ứng dụng của bạn giao tiếp với một protocol có implementation được host sẵn. Vì vậy, nếu Dormice ngừng phát triển, bạn chỉ cần thay đổi 2 URL rồi tiếp tục làm việc. Hãy viết agent của bạn dựa trên bề mặt E2B thay vì native API để giữ được lối thoát đó. Package native @dormice/sdk cũng chưa có trên npm, nên muốn dùng nó bạn phải build từ repository. Đây là lý do thứ hai để bắt đầu với đường dẫn tương thích.

Hãy chạy nó ở nơi bạn có thể chấp nhận mất dữ liệu. Dựng lại host bằng script, không đưa token vào bất kỳ prompt hoặc commit nào, và đưa mọi dữ liệu cần giữ ra khỏi sandbox theo lịch backup riêng của bạn.

FAQ

Dormice đã sẵn sàng cho production chưa?

Chưa, và chính dự án cũng nói rõ điều đó. Dòng trạng thái trong README cho biết hiện chưa có gì ở đó sẵn sàng cho production. Tính đến ngày 4 August 2026, repository mới khoảng bốn tuần tuổi, không có git tag và cũng không có release, nên bạn không có version number để cố định. Installer clone branch main, nghĩa là mỗi lần chạy sẽ lấy commit mới nhất. Ghi lại git -C /opt/dormice rev-parse HEAD sau mỗi lần cài đặt và giữ mọi dữ liệu quan trọng bên ngoài sandbox.

Dormice khác gì so với việc cấp cho agent một VM dùng xong rồi xóa?

VM dùng xong rồi xóa là một máy có SSH mà bạn tạo cho một phiên làm việc rồi xóa sau đó. Dormice là một execution API: chương trình của bạn gọi acquire, sau đó gọi exec, rồi nhận stdout và exit code, không có shell session ở giữa. VM phù hợp với người dùng hoặc agent cần một máy tính hoàn chỉnh trong một khoảng thời gian. Dormice phù hợp với ứng dụng chạy code được tạo tự động nhiều lần mỗi ngày và không muốn phải setup rồi teardown cả một máy cho mỗi lần chạy.

E2B SDK chính thức có thực sự hoạt động mà không cần sửa code không?

Có, nếu thay đổi cấu hình. Trỏ apiUrl và sandboxUrl đến /e2b/api và /e2b/envd trên daemon của bạn, rồi truyền token Dormice với prefix e2b_ làm API key. Command execution, PTY session, file transfer, signed URL và port proxy đều được bao phủ bởi end-to-end suite của dự án khi chạy qua package chính thức. Template building là phần còn thiếu đáng kể: e2b template build chưa được triển khai, nên template là một docker image mà bạn build và đăng ký bằng dor template add.

Một VPS 4 GB chứa được bao nhiêu sandbox?

Có khoảng 6 sandbox đang hoạt động cùng lúc nếu mỗi sandbox dùng 512 MiB, hoặc 3 nếu mỗi sandbox dùng đủ một gibibyte, sau khi dành khoảng 1 GB cho operating system, Docker và daemon. Sandbox đã đóng băng bị giới hạn bởi swap thay vì RAM. Vì vậy, swapfile mặc định 16 GB của installer có thể giữ khoảng 16 sandbox, với điều kiện mỗi sandbox từng dùng một gibibyte. Hãy đo trên hệ thống của bạn bằng free -m dưới tải thực tế, vì một sandbox chạy test suite có thể dùng nhiều hơn vài lần so với sandbox chỉ chạy một script nhỏ.

Vì sao Dormice cần đặt vm.swappiness thành 100?

Đóng băng một sandbox nghĩa là đẩy phần memory nhàn rỗi của sandbox đó sang swap. gVisor giữ memory của sandbox dưới dạng shared memory, còn Linux kernel sẽ không swap shared memory khi swappiness ở giá trị mặc định. Vì vậy, ở giá trị mặc định, thao tác đóng băng không thu hồi được gì và sandbox vẫn tiêu tốn toàn bộ memory. Dự án đo được 0 byte được thu hồi ở giá trị mặc định và 99.5 phần trăm được thu hồi khi đặt thành 100. Kiểm tra giá trị thực tế bằng sysctl vm.swappiness thay vì đọc các file cấu hình, vì một số cloud image được cung cấp với giá trị 0.