Cloudflare Sandboxes 정식 출시: AI 에이전트를 위한 격리된 컴퓨터 환경

섹션별 상세

AI 에이전트가 신뢰할 수 없는 코드를 안전하게 실행할 수 있도록 Cloudflare Containers 기반의 격리된 환경을 제공한다. 에이전트는 리포지토리 클론, 언어별 빌드, 개발 서버 실행 등 실제 개발자와 동일한 작업을 수행할 수 있는 완전한 컴퓨터 환경을 할당받는다. 이를 통해 개발자는 인프라 관리의 부담 없이 에이전트의 논리 구현에만 집중할 수 있다.

typescript

import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request: Request, env: Env) {
    const sandbox = getSandbox(env.Sandbox, "agent-session-47");
    await sandbox.gitCheckout("https://github.com/org/repo", {
      targetDir: "/workspace",
      depth: 1,
    });
    return sandbox.exec("npm", ["test"], { stream: true });
  },
};

Cloudflare Sandbox를 생성하고 특정 리포지토리를 클론한 뒤 테스트 명령을 실행하는 기본 예시

네트워크 계층에서 프로그래밍 가능한 송신 프록시를 통해 보안 자격 증명을 안전하게 주입하는 메커니즘을 구현했다. 에이전트 본체는 실제 비밀번호나 토큰에 직접 접근할 수 없으므로 자격 증명 유출 위험이 차단된다. 개발자는 인증 로직을 커스터마이징하여 에이전트가 비공개 서비스에 안전하게 접근하도록 제어할 수 있다.

typescript

class OpenCodeInABox extends Sandbox {
  static outboundByHost = {
    "my-internal-vcs.dev": (request, env, ctx) => {
      const headersWithAuth = new Headers(request.headers);
      headersWithAuth.set("x-auth-token", env.SECRET);
      return fetch(request, { headers: headersWithAuth });
    }
  }
}

에이전트에게 자격 증명을 노출하지 않고 네트워크 계층에서 인증 토큰을 주입하는 코드

단순한 요청-응답 루프를 넘어 실제 터미널과 동일한 피드백 루프를 제공하는 PTY(의사 터미널) 기능을 지원한다. WebSocket을 통해 프록시되는 터미널 세션은 xterm.js와 호환되어 에이전트와 인간 개발자가 실시간으로 출력을 모니터링하고 상호작용할 수 있다. 출력 결과가 서버 측에 버퍼링되어 연결이 끊겨도 이전 상태를 그대로 이어서 볼 수 있는 것이 특징이다.

상태가 유지되는(Persistent) 코드 실행 컨텍스트를 제공하여 데이터 분석 및 스크립팅 효율을 높였다. 기존의 일회성 실행 방식과 달리 변수, 임포트 내역, 데이터프레임 등이 호출 간에 유지되어 Jupyter 노트북과 유사한 워크플로우가 가능하다. 이를 통해 에이전트는 이전 단계에서 로드한 데이터를 다음 단계에서 즉시 활용하여 복잡한 분석 작업을 수행한다.

스냅샷 기능을 통해 컨테이너의 디스크 상태와 OS 설정을 그대로 보존하고 즉시 복구할 수 있는 환경을 구축했다. 에이전트가 휴면 상태일 때 자동으로 스냅샷을 찍어 R2에 저장하며, 재개 시 수 초 내에 이전 작업을 이어갈 수 있게 한다. 이는 긴 설치 과정(npm install 등)을 생략하게 해주어 나이브한 재생성 방식 대비 복구 속도를 30초에서 2초로 단축시킨다.

근거

나이브한 세션 재생성에는 30초가 소요되지만, 백업 복원 방식을 사용하면 2초로 단축된다. — Waking up quickly with snapshots 섹션 마지막 문단

용어 해설

샌드박스(Sandbox): — 외부의 영향으로부터 격리된 안전한 실행 환경을 의미한다. AI 에이전트가 신뢰할 수 없는 코드를 실행하거나 리포지토리를 빌드할 때 시스템 전체에 영향을 주지 않도록 보호하는 역할을 한다.
의사 터미널(PTY): — 물리적 터미널 장치를 소프트웨어로 에뮬레이션한 인터페이스이다. AI 에이전트가 실제 개발자처럼 터미널 출력을 실시간으로 스트리밍하고 상호작용할 수 있게 해주는 핵심 기술이다.
스냅샷(Snapshot): — 특정 시점의 컨테이너 디스크 상태, OS 설정, 설치된 종속성 등을 그대로 저장하는 기술이다. 에이전트가 작업을 중단했다가 다시 시작할 때 긴 설치 과정 없이 즉시 이전 상태를 복구할 수 있게 한다.
송신 프록시(Egress Proxy): — 내부 네트워크에서 외부로 나가는 트래픽을 중계하는 서버이다. 이 아티클에서는 에이전트에게 직접 노출하지 않고도 네트워크 계층에서 인증 자격 증명을 안전하게 주입하는 용도로 사용된다.

근거 모음

근거

표준 요금제 사용자는 라이트 인스턴스 기준 최대 15,000개의 동시 인스턴스를 실행할 수 있다. — Higher limits and Active CPU Pricing 섹션

기술

Cloudflare Sandboxes
Cloudflare Containers
Cloudflare Workers
R2
Python
JavaScript
TypeScript

활용 사례

AI 코딩 에이전트의 코드 빌드 및 테스트 실행
데이터 분석 에이전트의 상태 유지 스크립팅
신뢰할 수 없는 사용자 코드의 안전한 실행 환경
에이전트 기반의 실시간 개발 서버 미리보기

언급된 리소스

문서@cloudflare/sandbox SDK