cloudflare/computer

Cloudflare Computer – 개요

Cloudflare Computer는 Cloudflare Durable Object를 기반으로 하는 가상 파일 시스템을 제공하는 라이브러리입니다. Durable Object는 파일 데이터를 SQLite에 저장하며, 라이브러리는 세 가지 교체 가능한 "백엔드"를 통해 해당 파일 시스템을 읽고 쓰는 코드를 실행할 수 있게 합니다.

백엔드	작동 방식	제공 기능
컨테이너	SQLite 상태는 FUSE 마운트를 통해 샌드박스 Linux 컨테이너에 투영됩니다. 데몬(`computerd`)이 컨테이너 내에서 실행되어 Cap'n-Proto-over-WebSocket RPC 채널을 통해 FS를 노출합니다.	완전한 Linux 사용자 공간, 실제 바이너리, 네트워크 액세스 – 임의 도구(예: `pandoc`, `git`)를 실행해야 할 때 이상적입니다.
격리 셸	Cloudflare Dynamic Worker 내에서 경량 just-bash 셸을 실행합니다. Workers RPC를 통해 Durable Object를 직접 호출하므로 추가 저장소 동기화가 없습니다.	매우 빠른 셸 명령, 컨테이너 오버헤드 없음, 그러나 셸 호환 도구만 가능합니다.
격리 JavaScript	ECMAScript 모듈을 실행하는 새 Dynamic Worker를 시작합니다. 모듈은 Workspace에서 지원하는 `node:fs/promises` 유사 API와 특수 호스트 모듈(`ws:git`, `ws:artifacts`, `ws:container`)을 볼 수 있습니다.	가상 FS를 읽고 쓰고 Cloudflare 제공 서비스를 호출하는 JavaScript 코드를 실행합니다.

세 백엔드 모두 단일 진입점을 통해 액세스됩니다.

await workspace.runtime.exec(source, { backend: "container" })

source는 셸 명령(셸 백엔드의 경우) 또는 ES 모듈(JavaScript 백엔드의 경우)일 수 있습니다. Workspace는 백엔드 없이 생성할 수도 있으며 파일 시스템 API만 노출합니다.

AI / 에이전트에게 중요한 이유

많은 AI 에이전트 아키텍처는 지속적이고 변경 가능한 작업 공간이 필요하며, 여기서 다음을 수행할 수 있습니다.

중간 파일(예: 다운로드한 이미지, 생성된 코드)을 저장합니다.
외부 도구(컴파일러, 이미지 프로세서, git)를 실행하여 파일을 변환합니다.
여러 호출 또는 워커 간에 동일한 상태를 공유합니다.

Cloudflare Computer는 정확히 이를 제공하지만 Cloudflare의 엣지 플랫폼에서 호스팅되므로 작업 공간이 AI 모델 추론 워커와 가깝고 Durable Object 인식 서비스에서 액세스할 수 있습니다.

주요 기능

Durable-Object 기반 지속성 – Durable Object 내의 SQLite는 강력한 일관성과 자동 복제를 보장합니다.
플러그형 실행 백엔드 – 전체 Linux 컨테이너, 경량 Bash 셸 또는 JavaScript 모듈 중에서 선택할 수 있으며 모두 동일한 FS 표면을 사용합니다.
FUSE 스타일 마운트 – 컨테이너 백엔드는 가상 FS를 실제 마운트로 제공하여 모든 Linux 바이너리가 이를 조작할 수 있습니다.
구조화된 RPC – Durable Object와 컨테이너 데몬 간의 통신은 Cap'n-Proto-over-WebSocket 프로토콜(@cloudflare/computer-rpc)을 사용합니다.
AI 에이전트 예제에 대한 일류 지원 – 저장소에는 일반적인 에이전트 워크플로를 보여주는 많은 즉시 실행 가능한 데모(예: 일회성 pi 에이전트, TanStack AI 채팅 루프, PDF 생성 튜토리얼)가 포함되어 있습니다.
성능 테스트 완료 – 벤치마크는 FUSE 마운트가 메타데이터 집약적 워크로드에서 실제 디스크보다 우수함을 보여줍니다.

일반적인 사용 사례

에이전트 도구 실행 – LLM 기반 에이전트는 작업 공간에 git clone 실행, 코드 컴파일 또는 pandoc 호출을 요청하여 markdown을 PDF로 변환할 수 있습니다. 모두 컨테이너 백엔드를 통해 가능합니다.
RAG 스타일 데이터 파이프라인 – 가져온 웹 콘텐츠를 저장하고, 텍스트 처리 스크립트를 실행하고, 정리된 데이터를 모델에 다시 공급합니다. 모두 동일한 Durable Object 작업 공간 내에서 수행됩니다.
다중 런타임 실험 – think-compare-runtimes 예제를 사용하여 컨테이너, Bash 워커, JavaScript 워커에서 작업이 어떻게 실행되는지 비교합니다.
아티팩트 게시 – 작업 공간 내에서 프로젝트를 생성하고 artifacts 예제를 사용하여 Cloudflare Artifacts에 게시합니다.

성숙도 및 안정성

최상위 @cloudflare/computer 패키지는 핵심 API에 대해 안정적으로 표시되지만 컨테이너 및 워커 셸 백엔드는 여전히 실험적이며 프로덕션에 권장되지 않습니다.
기본 @cloudflare/dofs(Durable Object FS)는 안정적입니다.
자세한 상태 표는 packages/computer/README.md#status에 있습니다.

시작하기

패키지 설치:
```
npm i @cloudflare/computer
```
패키지별 README(packages/computer/README.md)를 따르세요:
- Workspace를 생성하는 Durable Object 설정.
- 백엔드를 선택하고 workspace.runtime.exec를 호출합니다.
- 제공된 예제 실행(npm run build:types && npm run dev:example/<name>).
빠른 데모를 위해 튜토리얼 예제를 시도하세요. markdown 레시피를 작성하고, 컨테이너에서 pandoc을 실행하고, PDF를 반환하는 단일 엔드포인트를 구축합니다.

문서 및 리소스

설계 사양 – docs/(미래 지향적, 의도만).
성능 수치 – docs/19_performance.md.
예제 – examples/ 폴더를 참조하세요. 각 하위 폴더에는 자체 README가 있습니다.
기여 가이드 – CONTRIBUTING.md, COLLABORATORS.md.

라이선스

MIT.

cloudflare/computer