Cloudflare Computer
Durable Object 안의 가상 파일시스템에 실행 백엔드를 갈아 끼우는 Cloudflare 패키지
npm install @cloudflare/computerDurable Object 안에서 도는 가상 파일시스템입니다. 권위 있는 상태는 SQLite 가 들고 있고, 그 위에 실행 표면 하나가 붙어 백엔드를 갈아 끼웁니다. 컨테이너에 FUSE 로 마운트해 진짜 리눅스 유저랜드를 쓰거나, Dynamic Worker 안에서 셸이나 자바스크립트 모듈만 돌리는 선택지가 있습니다. 저장소가 프리뷰이며 프로덕션에 쓰지 말라고 명시합니다.
판단
이럴 때 씁니다
- 에이전트에게 파일시스템을 주되 그 상태가 요청이 끝나도 남아 있어야 할 때
- 같은 작업을 진짜 컨테이너와 격리 워커에서 각각 돌려 비용과 성능을 비교하고 싶을 때
- 빌드나 변환처럼 실제 바이너리 실행이 필요한 단계를 에이전트 흐름 안에 넣어야 할 때
- 파일시스템만 필요하고 실행 백엔드는 아예 붙이지 않아도 되는 경우
이럴 땐 쓰지 마세요
- 지금 프로덕션에 올려야 하는 작업일 때. 저장소가 프리뷰이며 적합하지 않다고 직접 밝힙니다
- API 안정성이 전제여야 하는 경우. 설계가 바뀔 수 있다고 예고돼 있습니다
- Cloudflare Workers 와 Durable Objects 를 쓰지 않는 스택일 때
- 대용량 순차 입출력이 지배적인 작업일 때. FUSE 마운트가 이 구간에서 실제 디스크에 뒤집니다
차별점
- 상태를 컨테이너가 아니라 Durable Object 의 SQLite 가 쥐고 있어서 실행 환경을 버려도 파일시스템이 남습니다.
- 실행 진입점이 exec 하나로 통일돼 있어 컨테이너와 격리 워커를 같은 코드로 바꿔 끼웁니다.
- 격리 셸 백엔드는 Workers RPC 로 권위 저장소에 바로 닿기 때문에 두 번째 저장소나 동기화 왕복이 없습니다.
- 백엔드 없이 Workspace 만 만들어 파일시스템 단독으로도 쓸 수 있습니다.
워크플로
- 01@cloudflare/computer 를 설치하고 Durable Object 에 Workspace 를 붙입니다.
- 02쓸 백엔드를 안정적인 ID 로 등록합니다. 컨테이너, 격리 셸, 격리 자바스크립트 중에서 고르며 여러 개를 동시에 등록해도 됩니다.
- 03workspace.runtime.exec(source, { backend }) 하나로 실행합니다. 고른 백엔드가 source 를 셸 명령으로 볼지 ECMAScript 모듈로 볼지 결정합니다.
- 04백엔드는 첫 사용 시점에 지연 연결되므로 등록만 해 두고 실제 호출은 필요할 때 합니다.
- 05egress 정책이 필요하면 백엔드별로 none, all, 사용자 정의 중에서 지정합니다.
주요 명령
| 명령 | 설명 |
|---|---|
npm install @cloudflare/computer | 최상위 Computer 패키지를 설치합니다. Durable Object 쪽에서 소비합니다. |
workspace.runtime.exec(source, { backend }) | 등록한 백엔드 하나를 골라 실행합니다. 실행 진입점은 이것 하나입니다. |
docker run ghcr.io/cloudflare/computerd | 샌드박스 컨테이너 안에서 FUSE 마운트와 RPC 서버를 담당하는 computerd 데몬입니다. |
함정
설치 전에 확인하세요
- README 가 PREVIEW ONLY 라고 못박고 프로덕션에 적합하지 않다고 명시합니다. 실험과 프로토타입 범위로 봐야 합니다.
- docs/ 아래 명세는 앞을 내다본 문서라 현재 코드 설명이 아닙니다. 저장소가 의도로 읽으라고 따로 경고합니다.
- computerd 의 FUSE 마운트는 메타데이터가 많은 작업에서 실제 디스크보다 빠르지만 큰 순차 입출력에서는 뒤집니다. 워크로드 성격에 따라 방향이 갈립니다.
- 요청하지 않은 풀 리퀘스트는 받지 않습니다. 이슈와 디스커션이 공개 기여 경로입니다.
- packages/computer 는 저장소 스스로 작업 진행 중이라고 표시한 상태입니다.
검토 메모
공식 문서·릴리스·공개 자료를 바탕으로 정리한 편집 메모입니다.
저는 이 패키지를 에이전트 샌드박스라기보다 상태의 소유권을 옮긴 실험으로 읽습니다. 보통은 컨테이너가 파일을 들고 있고 컨테이너가 죽으면 같이 사라지는데, 여기서는 Durable Object 의 SQLite 가 권위를 쥐고 실행 환경은 그 위에 잠깐 붙었다 떨어지는 부속입니다. 그래서 백엔드를 컨테이너에서 격리 워커로 바꿔도 작업하던 파일이 그대로 남습니다.
다만 도입을 권하지는 않겠습니다. README 가 프리뷰이며 프로덕션에 적합하지 않다고 직접 밝혔고, docs 아래 명세도 현재 코드가 아니라 앞으로의 의도라고 스스로 한정했습니다. 이 두 문장을 읽지 않고 설계를 얹으면 나중에 API 가 바뀔 때 되돌릴 곳이 많아집니다.
지금 시점에서 이 저장소의 값어치는 코드보다 예제 디렉터리에 있다고 봅니다. 같은 작업을 컨테이너와 워커 셸과 워커 자바스크립트에 각각 태워 보는 예제가 나란히 있어서, 내 작업이 진짜 리눅스 유저랜드를 필요로 하는지 아니면 격리 워커로 충분한지를 실제로 재 볼 수 있습니다. 그 판단만 얻어도 충분한 방문이라고 생각합니다.
의존할 대상을 고를 때는 저장소가 작은 모노레포라는 점을 감안하시기 바랍니다. 파일시스템 본체와 RPC 배선, 컨테이너 안에서 도는 데몬이 각각 다른 패키지로 나뉘어 있고, 최상위 Computer 패키지는 저장소가 스스로 작업 진행 중이라고 표시해 두었습니다. 성능 문서도 같은 태도로 읽는 편이 낫습니다. FUSE 마운트가 메타데이터가 많은 작업에서 실제 디스크를 앞선다는 결과는 의미가 있지만, 큰 파일을 순차로 읽고 쓰는 작업에서는 뒤집니다. 내 작업이 어느 쪽에 가까운지를 먼저 재고 백엔드를 고르는 순서를 권합니다.
비교
일반적인 에이전트 샌드박스가 컨테이너를 띄우고 그 안에 파일을 두는 방향이라면, 이쪽은 파일시스템을 Durable Object 에 먼저 두고 실행 환경을 나중에 갈아 끼우는 방향입니다. 덕분에 실행 백엔드를 바꿔도 상태가 따라오지만, 아직 프리뷰라 안정성을 전제로 고를 수는 없습니다.
최근 변경
@cloudflare/computer 0.2.1은 실행 runtime의 소유권과 identity 추적을 명시적으로 보강했습니다. exec lifecycle과 post-exec pull을 runtime에 묶고, preflight sync 실패 시 실행을 중단하며 transport loss 뒤 sync 재시도와 shell reconnect를 안전하게 처리합니다. container egress 설정 실패 재시도와 실행 추적 한계도 추가해 연결 손실 시 상태가 섞이는 문제를 줄였습니다.