BitMiracle-AI/Dormice

Dormice – “에이전트 샌드박스계의 SQLite”

개요

• Dormice는 AI 에이전트를 위해 설계된 셀프 호스팅 샌드박스 플랫폼입니다. 단일 머신이나 머신 클러스터에서 초당 사용료를 지불하지 않고도 다수의 격리된 실행 환경(샌드박스)을 운영할 수 있습니다. 샌드박스는 영구적이며 호스트에 유지되고, 유휴 시간이 길어질수록 비용이 저렴해집니다.

AI에게 중요한 이유

• 현대의 LLM 기반 에이전트는 코드 실행, 파일 저장, 호출 간 상태 유지를 위한 공간이 필요합니다. 공용 샌드박스 서비스(예: E2B)는 샌드박스가 존재하는 매 초마다 비용을 청구하므로 개발자는 이를 일회성으로 취급해야 합니다. Dormify는 이 모델을 뒤집습니다. 하드웨어를 직접 소유하고 샌드박스는 영구적으로 존재하며, 유휴 샌드박스는 거의 리소스를 소비하지 않습니다(동결 후 수 MB의 RAM만 점유).

핵심 개념

• acquireSandbox(userKey) – 고려해야 할 유일한 작업입니다. 이는 멱등성을 가집니다. 동일한 키는 항상 동일한 샌드박스를 반환하며, 존재하지 않으면 생성하고, 동결되어 있으면 깨우며, 필요시 아카이브에서 복원합니다.
• 라이프사이클 상태 – active → frozen → stopped → archived. 각 단계마다 리소스 사용량이 감소합니다. 동결된 샌드박스는 약 50ms 내에 재개될 수 있으며, 아카이브된 샌드박스는 S3에 저장되어 필요시 복원됩니다.
• 단일 바이너리 배포 – 데몬 하나(Fastify + SQLite 원장)와 선택적인 웹 콘솔용 게이트웨이만 있으면 됩니다. Kubernetes, 외부 데이터베이스, 복잡한 오케스트레이션이 필요 없습니다.
• E2B 호환 API – 데몬은 두 개의 URL 접두사에서 E2B 프로토콜을 구현하므로, 공식 e2b SDK를 사용하는 기존 코드는 URL과 토큰만 변경하면 작동합니다.

주요 구성 요소 (monorepo 레이아웃)

패키지	역할
packages/server	핵심 데몬: HTTP API, SQLite 원장, 라이프사이클 엔진
packages/gateway	클러스터 입구, 설정/템플릿 저장, 웹 콘솔 제공
packages/sdk	네이티브 TypeScript 클라이언트 (@dormify/sdk)
packages/cli	운영자를 위한 dor 명령줄 도구
packages/console	브라우저를 통해 샌드박스를 관리하는 React SPA
e2e	실제 e2b SDK로 데몬을 구동하는 블랙박스 엔드투엔드 테스트 스위트
examples	즉시 실행 가능한 데모 (네이티브 SDK, 공식 e2b SDK, 상주 에이전트)

설치 (한 줄 명령어)

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

• 베어메탈 Ubuntu/Debian x86_64 호스트에서 작동합니다(root 권한으로 실행). 스크립트는 Docker, gVisor (runsc), zstd를 설치하고, 스왑을 설정하며 systemd 서비스를 작성합니다.
• 설치 프로그램은 멱등성을 가집니다. 재실행 시 코드가 업그레이드되고 dor doctor로 설치가 검증됩니다.
• 동일한 클러스터에 두 번째 노드를 추가하는 것은 추가 명령어 하나로 가능합니다 (--role node --gateway http://<first>:80).

빠른 사용법 (TypeScript SDK)

import { Dormice } from '@dormice/sdk';
const client = new Dormice({ endpoint: 'http://127.0.0.1:3677', token: process.env.DORMICE_API_TOKEN! });
await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
const res = await client.execCommand('my-agent', 'python3 -c "print(6*7)"');
console.log(res.exitCode, res.stdout); // 0 42
await client.writeFiles('my-agent', [{ path: 'notes.txt', content: 'survives freeze and stop' }]);
await client.destroySandbox('my-agent');

• 동일한 작업은 curl 또는 dor CLI (dor sandbox ls, dor exec, dor push 등)로도 수행할 수 있습니다.

E2B 호환성

• 데몬은 /e2b/api 및 /e2b/envd에서 E2B API를 노출합니다. 공식 e2b npm 패키지를 사용하는 기존 코드는 다음을 가리킬 수 있습니다:

apiUrl: 'http://127.0.0.1:3677/e2b/api',
sandboxUrl: 'http://127.0.0.1:3677/e2b/envd',
apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`

• 모든 주요 E2B 기능(샌드박스 생성, 일시 중지/재개, 스트리밍 I/O 명령 실행, PTY, 파일 작업, 서명된 업로드/다운로드 URL, 디렉토리 모니터링, 포트 프록시, 메트릭)이 지원됩니다. 일부 고급 기능(템플릿 빌드, xattr 메타데이터)은 의도적으로 구현되지 않았으며 명시적인 unimplemented 오류를 반환합니다.

웹 콘솔

• API 토큰(httpOnly 쿠키로만 저장)으로 로그인 후 http://127.0.0.1:3677/console에서 액세스할 수 있습니다.
• 실시간 샌드박스 상태를 표시하고, 생성/획득, 삭제, 파일 푸시/풀을 수행할 수 있으며, SDK, CLI 또는 E2B 클라이언트를 위한 복사/붙여넣기 스니펫을 제공합니다.
• SSH 터널 또는 리버스 프록시(Caddy 예제 제공)를 통해 로컬에서 액세스하도록 설계되었습니다. 스트리밍 출력은 버퍼링을 비활성화하는 프록시(flush_interval -1)를 사용할 때만 작동합니다.

콜드 아카이브 (선택적 S3 저장소)

• DORMICE_S3_* 환경 변수가 설정되면, 설정된 기간 동안 중지된 샌드박스는 tar-zstd로 압축되어 S3 호환 버킷에 업로드됩니다.
• 다음 acquireSandbox 호출 시, 데몬은 restoring 상태를 반환하고 아카이브가 다운로드 및 압축 해제될 때까지 진행 상황을 스트리밍합니다.
• S3가 설정되지 않은 경우, 샌드박스는 stopped 상태에서 멈추며 아카이브되지 않습니다.

Dormice를 사용하지 말아야 할 경우

• 머신이나 리전 간에 마이그레이션해야 하는 샌드박스가 필요한 경우 – Dormice는 샌드박스를 생성한 노드에 고정합니다.
• SLA가 포함된 완전 관리형 SaaS를 선호하는 경우 – 이는 호스팅된 E2B 제품입니다.
• 보안 모델상 하드웨어 수준의 격리(KVM/Firecracker)가 필요한 경우 – Dormice는 Docker + gVisor(사용자 공간 커널)를 사용하여 빠른 동결을 구현합니다.
• 워크로드가 Linux가 아닌 경우(예: Windows 바이너리).

개발 워크플로우

pnpm install
pnpm build      # 데몬, SDK, CLI, 콘솔 빌드
pnpm typecheck
pnpm lint
pnpm test        # 빌드된 데몬에 대해 e2e 스위트 실행

• 저장소는 pnpm monorepo를 사용하며, 모든 패키지는 packages/shared의 프로토콜 스키마(zod)를 공유합니다.

기여 모델

• 핵심 팀이 코드를 유지 관리합니다. 외부 기여자는 이슈를 제기할 수 있지만, 풀 리퀘스트는 허용되지 않습니다. 이 정책은 이미 운영 중인 클러스터의 안정성을 보호하기 위한 것입니다.

라이선스

• Apache-2.0.

---

결론: Dormice는 영구적인 상태와 낮은 유휴 비용이 필요한 AI 에이전트를 위해 맞춤화된 저비용 셀프 호스팅 샌드박스 환경을 제공합니다. E2B API를 모방하므로 기존 에이전트 코드는 최소한의 변경으로 자체 플랫폼으로 전환할 수 있으며, 운영자를 위한 웹 UI와 CLI도 제공합니다.