LLM Wiki

Cloudflare Computer — Durable Object 기반 에이전트 작업공간과 실행 백엔드

Properties3
descriptionSQLite 기반 영속 파일시스템과 Container·Worker Shell·JavaScript 실행 백엔드를 에이전트 도구로 묶는 Cloudflare preview 프로젝트.
tagsai-agents, dev-tools, typescript, cloudflare, open-source
aliasesCloudflare Computer, @cloudflare/computer, computerd

17 min read

Cloudflare Computer는 Durable Object의 SQLite 저장소를 기반으로 에이전트용 영속 작업공간을 만들고, 같은 파일 트리에 대해 Container·Worker Shell·격리 JavaScript를 선택 실행하게 하는 TypeScript preview 프로젝트다. @cloudflare/computer는 Workspace.fs, Workspace.runtime, AI SDK 도구, Git·Assets·Artifacts 연결면을 하나의 API 아래에 묶고, 컨테이너 쪽에는 computerd daemon과 FUSE/shim·capnweb 동기화를 둔다.

한눈에 보기

  • 프로젝트 성격: Cloudflare 공식 GitHub 저장소의 MIT 라이선스 TypeScript monorepo. 저장소 README와 @cloudflare/computer package README 모두 아직 PREVIEW ONLY이며 API가 불안정하고 production 사용에 적합하지 않다고 명시한다.
  • 핵심 추상화: 에이전트가 파일을 읽고 쓰고 검색하며 명령/코드를 실행하고 생성물을 publish할 수 있는 작은 portable working directory.
  • 상태 저장: Durable Object 자체의 SQLite가 기본 Workspace의 권위 저장소다. 파일은 content-addressed chunk/blob과 manifest·revision 로그를 사용하고, Container backend만 별도의 in-container VFS를 두어 push/pull한다.
  • 실행면: workspace.runtime.exec(source, options)가 공통 진입점이다. container-shell은 실제 Linux 명령, worker-shell은 just-bash 명령, worker-javascript는 ECMAScript module을 실행한다.
  • 에이전트 연결: @cloudflare/computer/tools에 AI SDK용 read, write, edit, ls가 있고 exec와 publish는 각각 명시적으로 opt-in한다. readonly: true는 읽기·목록만 남긴다.
  • 현재 버전 스냅샷: 고정 커밋의 @cloudflare/computer와 @cloudflare/computerd 버전은 0.1.0-alpha.1이다. 기능·지표는 2026-08-08 KST에 확인한 커밋 기준이며 현재 HEAD의 영속적 사실로 일반화하지 않는다.

공식 확인 — Workspace와 파일시스템

Workspace는 DO 저장소를 여는 host-side facade이며, workspace.fs는 node:fs/promises에서 영감을 받은 더 작은 비동기 API다.

  • 모든 메서드는 async이고 경로는 absolute POSIX-style이다.
  • readFile()의 기본 반환은 ReadableStream<Uint8Array>이며 "utf8"을 지정하면 문자열을 반환한다. 큰 파일을 Response·fetch·R2에 바로 연결하기 위한 설계다.
  • writeFile()은 string·Uint8Array·ReadableStream을 받으며, 스트림은 512 KiB chunk 단위로 staging·hashing된다. inode·dirent·chunk list·manifest는 source가 끝난 뒤 짧은 transaction으로 커밋된다.
  • mkdir, readdir, stat, find, ls, rm, grep, chmod, symlink, readlink, lstat, access 등 agent 작업에 필요한 좁은 표면을 제공한다.
  • R2 mount는 지정된 경로를 read-only로 노출하며 쓰기는 EROFS로 거부한다.
  • README의 한도는 Workspace당 약 10 GB이며 DO 저장소를 공유한다. Container 쪽 파일시스템은 메모리에 유지되므로 full monorepo보다 agent-scale 작업공간을 목표로 한다.

공식 확인 — 단일 runtime router

Workspace.runtime은 backend id를 실행 언어와 capability 계약에 매핑한다.

workspace.runtime.exec(source, options)
  ├─ container-shell      → full Linux shell / native binaries / processes
  ├─ worker-shell         → just-bash command in Dynamic Worker
  └─ worker-javascript    → ECMAScript module in fresh Dynamic Worker
  • exec, getExec, killExec, disposeExec를 제공하고 handle은 live ReadableStream 이벤트, result(), kill(), id, backend를 가진다.
  • 결과에는 status, exitCode, stdout/stderr, 선택적 structured value, push/pull·skip 상태가 들어간다.
  • command backend는 push → spawn → events/result → pull bracket을 사용한다. worker-shell은 host store를 직접 쓰므로 sync가 none이고 push/pull round-trip이 없다.
  • backend를 지정하지 않으면 첫 번째 configured backend가 선택된다. 문서와 source 모두 backend 선택 자체는 authorization이 아니며, public gateway는 server-side policy로 허용된 backend를 검증해야 한다고 명시한다.
  • 실행 handle은 result()로 drain하거나 event stream을 소비해야 하며, worker-javascript처럼 반환 후에도 실행이 진행되는 backend는 Durable Object eviction을 고려해 event/result drain 또는 alarm을 사용해야 한다.

Container backend — computerd·FUSE·capnweb

Container 경로는 packages/computerd/의 self-contained Node SEA binary를 sandbox image에 넣는 구조다.

  1. computerd가 /workspace에 FUSE mount 또는 userspace shim을 붙이고 in-container VFS와 exec runner를 소유한다.
  2. GET /health와 GET /__computerd/info로 상태를 노출하고, /api HTTP-batch와 /ws capnweb WebSocket transport를 제공한다.
  3. /connect는 daemon이 caller-supplied URL로 outbound WebSocket을 열도록 한다.
  4. CloudflareContainerBackend는 Cloudflare Containers API의 container.start, outbound HTTP interception, TCP /health probe를 사용한다.
  5. DO가 upgrade slot을 먼저 arm한 뒤 /connect를 호출하고, daemon의 outbound dial이 egress interception을 통해 DO의 handleFetch()로 되돌아오는 inverted WebSocket carrier를 사용한다.

WorkspaceRPC는 sync와 shell stub으로 나뉜다. sync는 ChangeEntry와 chunk hash를 스트리밍하고 hasObjects·fetchObjects·pushObjects로 필요한 blob만 전송한다. shell은 exec, getExec, killExec, disposeExec와 stdout/stderr/exit 이벤트를 제공한다. DO와 computerd는 version negotiation 없는 matched pair이므로 wire shape 변경은 lockstep rollout을 요구한다.

현재 문서가 밝히는 운영상의 주의점은 다음과 같다.

  • WebSocket이 중간에 끊기면 기존 Workspace를 재구성해야 하며 backend가 기존 session에 새 socket을 splice하지 않는다.
  • 기본 WebSocket endpoint는 해당 포트에 도달할 수 있는 모든 것을 신뢰한다. Cloudflare Containers에서는 owning DO만 접근한다고 가정하지만, broader network provider로 확장할 때 handshake auth가 필요하다.
  • computerd는 보통 entrypoint 사용자의 권한으로 실행되며 root 실행과 arbitrary shell command의 권한 경계는 open question이다.
  • daemon 자체는 on-disk persistence가 없으므로 container restart 시 in-memory VFS를 잃을 수 있고, UPSTREAM_URL sync가 재부팅 사이의 복구 경로다.

Worker Shell backend

WorkerShellBackend는 env.LOADER로 mint한 Dynamic Worker 안에서 just-bash를 실행한다.

  • Container가 필요 없고, filesystem RPC는 host DO의 동일한 SQLite store로 돌아가므로 두 번째 store나 sync round-trip이 없다.
  • globalOutbound: null로 Dynamic Worker 내부의 fetch()와 connect()를 막고, shell에서 host DO로 돌아가는 env.HOST RPC가 유일한 경로다.
  • git ...은 host-side workspace.git.cli(...)로, assets publish는 host-side assets publisher로 전달된다. R2 binding과 signing secret은 Dynamic Worker에 들어가지 않는다.
  • curl, html-to-markdown, python, sqlite, js-exec, yq, file, xan, jq는 feature group별로 import할 때만 번들에 포함된다.
  • just-bash의 stdout/stderr는 현재 실행 종료 시 한 번에 반환되는 fidelity gap이 있고, cross-request getExec reattach도 지원하지 않는다. native binary·npm·실제 언어 runtime·browser가 필요하면 Container를 사용한다.

Worker JavaScript backend — 격리된 module 실행

WorkerJavaScriptBackend는 매 실행마다 fresh Dynamic Worker를 만들고, caller가 제공한 ECMAScript module을 structured input/result 형태로 평가한다.

  • static import, literal dynamic import, top-level await, default-exported function 호출, cwd 기반 durable relative import를 지원한다.
  • node:fs/node:fs/promises는 isolate-local disk가 아니라 Workspace capability로 연결된다. caller module은 Workspace root 밖으로 lexical escape하거나 symlink component를 통과할 수 없다.
  • source/module graph·import depth·input/result/stdin/stdio·capability request/response bytes에 한도가 있고, 동시 실행 기본 한도는 24개, completed record retention 기본값은 60분/100개다.
  • globalOutbound: null이 기본이며, process.env에는 execution별로 전달한 값만 있고 Durable Object의 env/binding/secret은 노출되지 않는다. process.stdin도 caller가 준 bounded bytes만 읽는다.
  • ws:git와 ws:artifacts는 ambient network가 아닌 host RPC capability다. allowGitNetwork와 allowArtifactNetwork를 backend 생성 시 켜지 않는 한 remote operation은 거부되고 local git은 남는다.
  • read/read-write 권한이 서로 다른 backend 인스턴스로 고정된다. 그러나 backend id는 authorization이 아니므로 public gateway의 signed capability policy가 별도로 필요하다.
  • source는 path confinement와 symlink 검사를 거치지만, 문서 자체가 이를 동시적인 더 높은 권한 principal의 path replacement에 대한 atomic inode-style security boundary로 취급하지 말라고 경고한다.

Sync·충돌·ignore 의미론

Container와 DO 사이 sync는 파일 바이트를 ChangeEntry로 직접 싣지 않고 content-addressed chunk hash를 협상한다.

  • CHUNK_SIZE는 512 KiB이고 blob은 SHA-256으로 deduplicate된다.
  • push는 senderRev, 변경 stream, missing-object probe, object stream을 사용하고, fetch는 (rev, path) cursor로 재개한다.
  • push batch는 receiver 관점에서 transaction으로 적용되어 중간 실패 시 부분 batch를 남기지 않는다. pull은 network streaming 때문에 per-mutation checkpoint를 사용한다.
  • 한 Workspace 내부 mutation은 DO input gate와 per-Workspace FIFO로 순서화되지만, 서로 다른 Container가 같은 path를 동시에 쓰면 merge/conflict detection 없이 last-write-wins다. agent 간 공유 mutable file을 CRDT처럼 사용하면 안 된다.
  • 기본 ignore는 node_modules이며 caller list가 기본값을 대체한다. ignored path는 container-side exec에서는 존재하지만 DO Workspace.fs에서는 readdir·stat·readFile에 보이지 않는다.
  • 안전한 패턴은 한 workspace에 active writer 하나, agent별 subtree 분할, 명시적 handoff 때 pull() 호출이다.

Agent tool plane

@cloudflare/computer/tools는 AI SDK ToolSet을 만들며 기본 도구 이름은 read, write, edit, ls다.

  • read: 1-indexed line window, 기본 2,000 lines/256 KiB cap, truncation 시 nextOffset 반환
  • write: 기본 2 MiB UTF-8 cap, 기존 executable mode 보존
  • edit: original content 기준 exact replacement, overlap 거부, line-ending 복원, unified patch 반환
  • ls: 한 단계 directory listing
  • exec: shell command backend를 caller가 설명과 함께 opt-in한 경우에만 제공하며 arbitrary shell command이므로 연결을 신중히 구성해야 함
  • publish: configured workspace.assets가 있을 때만 제공하며 만료가 있는 share URL을 생성
  • readonly: true: mutation·exec·publish를 모두 제거하고 read/ls만 제공

이 구조는 모델에게 무제한 “컴퓨터”를 주는 것이 아니라, file mutation·command execution·publishing을 각각 명시적인 도구와 backend capability로 분리하는 설계다.

공식 보안·운영 경계

공식 .github/SECURITY.md와 README는 이 프로젝트를 early preview/experimental 상태로 설명하며 production security guarantee에 의존하지 말라고 한다. 문서와 source에서 확인되는 방어는 다음과 같다.

  • Dynamic Worker의 global outbound 차단, host capability loopback, caller별 input/env/stdin 및 output byte cap
  • Workspace root·symlink traversal 검사, backend별 read/read-write capability 고정
  • command exec와 publish의 opt-in, AI SDK readonly 모드
  • Container/DO sync에서 content-addressed blob과 transaction·cursor 기반 복구

동시에 아직 닫히지 않은 경계가 있다.

  • computerd/capnweb handshake authentication은 현재 미구현·reserved 상태다.
  • matched DO/daemon wire version negotiation이 없다.
  • Container process user/ownership과 FUSE soft-fail 정책은 open question이다.
  • large sequential I/O와 full npm install은 FUSE overhead가 크다.

해석 — 에이전트의 “컴퓨터”를 workspace capability로 축소하기

이 저장소의 핵심은 GUI desktop automation이 아니라 durable workspace + pluggable execution + explicit tool/capability boundary다.

  1. 파일이 공통 상태면 backend를 바꿀 수 있다. 같은 Workspace에서 빠른 text shell을 먼저 쓰고 native binary가 필요할 때만 Container로 올리는 execution ladder를 만든다.
  2. 격리는 모델 instruction이 아니라 construction-time capability에서 시작한다. backend별 module, outbound, filesystem root, 네트워크·Artifacts 권한을 생성 시 고정하고 runtime의 문자열 backend 선택에 authorization 의미를 부여하지 않는다.
  3. 동기화는 저장 내구성이지 협업 merge가 아니다. content-addressed chunk와 cursor는 재시작·재전송 비용을 낮추지만, 동시 writer의 의미론은 last-write-wins다.
  4. agent tool은 작은 표면을 선호한다. read/edit/ls와 opt-in exec/publish로 나눈 형태는 “전부 가능한 shell”보다 operator가 승인·감사할 capability 단위를 제공한다.
  5. Cloudflare runtime에 강하게 결합된다. Durable Objects SQLite, Worker Loader, Dynamic Worker, Containers, R2, Workers RPC가 모두 함께 작동해야 하므로 다른 플랫폼에서 그대로 portable한 runtime이라기보다 Cloudflare-native agent substrate에 가깝다.

변화하는 GitHub 스냅샷

GitHub REST API, main ref, git ls-remote를 2026-08-08 KST에 확인한 값이다.

  • 5,801 stars · 292 forks · 21 open issues
  • TypeScript · MIT · archived 아님
  • 기본 브랜치: main
  • 확인 커밋: 8758b51c8891c211dddd1903d2ee2d12a75ac7ff
  • 커밋 메시지: dofs: Guard the staged-chunk link path
  • 커밋 시각: 2026-08-07T15:16:11Z author / 2026-08-07T15:28:16Z committer
  • GitHub API signature: unsigned
  • README size: 6,067 bytes
  • README byte SHA-256: 6583c8aaccc3492b516678759235f41e843e6a15f45ed1b0b3fcccaefd8e6270

아직 검증하지 않은 것

이번 노트는 고정 커밋의 GitHub metadata, README·package README, docs, package metadata, selected TypeScript source, security notice를 읽어 정리한 것이다. 다음은 이 환경에서 실행하지 않았다.

  • npm install/npm ci, dependency resolution, build, bundle, typecheck, lint, unit/integration/worker tests
  • @cloudflare/computer를 실제 Durable Object Worker에 설치하고 SQLite migration을 적용하는 과정
  • computerd SEA binary build, Docker image build, FUSE mount/shim 실행, /health·/ws·/connect end-to-end
  • Cloudflare Containers, Worker Loader, Dynamic Worker, R2, Artifacts, Workers RPC의 실제 배포·요금·quota 동작
  • Container·Worker Shell·Worker JavaScript 간 실제 file sync, restart recovery, backpressure, last-write-wins 재현
  • AI SDK tool 호출, arbitrary command execution, publish URL, ws:git/ws:artifacts capability 및 네트워크 권한 테스트
  • 독립 보안 감사, sandbox escape, symlink race, same-user hostile process, handshake exposure 검증
  • docs/19_performance.md의 benchmark 수치와 npm install 시간을 이 환경에서 재실행

따라서 이 노트에서 “지원한다”는 표현은 해당 고정 커밋의 문서·소스가 그 경로를 정의한다는 뜻이며, 이 환경에서 설치·배포·실행 성공을 재현했다는 뜻이 아니다. 사용자가 제공한 주장은 저장 요청과 저장소 URL뿐이며, 기능·지표·보안 설명은 고정 커밋의 공식 문서와 source를 기준으로 분리했다.

관련 노트

출처 및 검증

백링크