샌드박스 클라이언트

이 페이지에서 샌드박스 작업을 실행할 위치를 선택할 수 있습니다. 대부분의 경우 SandboxAgent 정의는 그대로 유지하고 sandbox 실행 옵션에서 샌드박스 클라이언트와 클라이언트별 옵션을 변경합니다.

선택 가이드

목표	시작점	이유
macOS 또는 Linux에서 신뢰할 수 있는 로컬 개발	UnixLocalSandboxClient	관리되는 워크스페이스에서 호스트 프로세스를 실행하며, OS 수준의 격리는 추가하지 않습니다.
기본 컨테이너 격리	DockerSandboxClient	특정 이미지를 사용하여 Docker 내부에서 작업을 실행합니다.
호스팅 환경에서 실행	호스팅형 샌드박스 클라이언트	제공자가 관리하는 환경을 사용하며, 격리 수준은 제공자와 구성에 따라 달라집니다.

로컬 클라이언트

대부분의 사용자는 다음 두 샌드박스 클라이언트 중 하나로 시작하면 됩니다.

클라이언트	설치 요구 사항	선택하는 경우
UnixLocalSandboxClient	없음	macOS 또는 Linux에서 신뢰할 수 있는 로컬 개발을 수행하거나, 외부에서 격리된 환경 내에서 실행하는 경우입니다.
DockerSandboxClient	로컬에서 사용 가능한 Docker CLI	컨테이너 격리가 필요하거나 로컬 환경을 동일하게 맞추기 위해 특정 이미지가 필요한 경우입니다.

UnixLocalSandboxClient는 macOS와 Linux 모두에서 PTY를 사용하는 명령을 포함한 셸 명령을 호스트 프로세스로 실행합니다. 이 클라이언트는 OS 수준의 파일시스템 또는 네트워크 격리를 추가하지 않습니다. 명령은 선택된 호스트 사용자의 권한으로 실행되며, 외부에서 적용하는 격리의 제약을 받습니다. 워크스페이스 디렉터리, 명령의 작업 디렉터리, HOME 환경 변수는 명령을 워크스페이스 내부로 제한하지 않습니다.

새 Unix 로컬 세션마다 별도의 임시 워크스페이스가 할당됩니다. Manifest.root는 논리적 경로이며, workspaceBaseDir은 임시 워크스페이스의 상위 디렉터리를 지정합니다. 어느 설정이든 같은 값을 사용한다고 해서 새로 생성되는 세션이 워크스페이스를 공유하지는 않습니다. 활성 세션을 재사용하면 해당 세션의 워크스페이스를 공유합니다. Unix 로컬 세션과 워크스페이스를 분리해도 OS 격리 경계가 형성되지는 않습니다.

Unix 로컬 경로 권한 부여는 지원되는 호스트 소스 접근과 SDK 파일 API를 제한합니다. readOnly 권한 부여는 SDK 파일 API가 해당 경로에 쓰는 것을 방지하지만, 임의의 셸 명령을 제한하지는 않습니다. 명령은 경로 권한이 부여되지 않아도 프로세스 권한과 외부 격리에서 허용하는 호스트 경로에 접근할 수 있습니다. 개념을 참조하세요.

신뢰할 수 없는 입력의 영향을 받는 명령을 포함하여 신뢰할 수 없는 명령을 실행하려면, 적절하게 구성된 DockerSandboxClient나 호스팅형 백엔드를 선택하거나 외부 격리를 제공하세요. 애플리케이션에 필요한 파일시스템, 네트워크, 프로세스 격리에 맞는 백엔드와 구성을 선택하세요.

Unix 로컬에서 Docker로 전환하려면 에이전트 정의는 그대로 유지하고 클라이언트만 변경하세요.

Docker 사용

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { DockerSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const result = await run(agent, 'Inspect the workspace.', {
  sandbox: {
    client: new DockerSandboxClient({ image: 'node:22-bookworm-slim' }),
  },
});

console.log(result.finalOutput);

일반적으로 동일한 에이전트를 두 로컬 클라이언트 중 어느 쪽으로도 실행할 수 있습니다.

로컬 클라이언트 간 전환

import {
  DockerSandboxClient,
  UnixLocalSandboxClient,
} from '@openai/agents/sandbox/local';

const client = process.env.USE_DOCKER
  ? new DockerSandboxClient({ image: 'node:22-bookworm-slim' })
  : new UnixLocalSandboxClient();

DockerSandboxClient는 클라이언트 생성자나 실행별 sandbox.options에 networkMode: 'none'을 설정하지 않는 한 Docker의 기본 네트워킹을 사용합니다. 'none' 모드는 네트워킹이 비활성화된 상태로 컨테이너를 시작합니다. 이 모드는 exposedPorts와 함께 사용할 수 없으며, SDK는 컨테이너를 생성하거나 재개하기 전에 해당 구성을 거부합니다. 현재는 다른 명시적 networkMode 값을 지원하지 않습니다.

생성되는 컨테이너에 사용자 정의 레이블을 적용하려면 DockerSandboxClient 생성자나 실행별 sandbox.options에 labels: Record<string, string>을 설정하세요. 실행별 labels 레코드는 생성자의 레코드와 병합되지 않고 이를 대체합니다. SDK는 문자열이 아닌 값을 거부하며, 자체 소유권 확인을 위해 openai-agents-sandbox, openai-agents-sandbox.session-identity, openai-agents-sandbox.mount-authority-fingerprint를 예약합니다.

SDK는 사용자 정의 레이블을 직렬화된 Docker 세션 상태에 복사합니다. 해당 상태를 명시적으로 재개할 때 호출자가 제공한 레이블은 저장된 레이블 레코드와 정확히 일치해야 합니다. 레이블을 변경하려면 새 샌드박스 세션을 시작하세요. 활성 컨테이너를 재사용할 때도 구성된 모든 레이블이 여전히 필요한 값을 가지고 있는지 확인합니다. SDK 외부에서 추가된 관련 없는 레이블은 재사용을 방해하지 않습니다.

세션 소유권

수명 주기 관리 방식은 두 가지입니다.

방식	전달하는 값	세션을 종료하는 주체	사용하는 경우
SDK 소유	sandbox: { client }	러너	샌드박스가 한 번의 실행 동안만 유지되면 되는 경우입니다.
개발자 소유	sandbox: { session }	개발자 코드	실행 후 파일을 검사하거나, 동일한 활성 세션을 재사용하거나, 여러 실행을 조율해야 하는 경우입니다.

정상적으로 완료되거나 실패하면 러너는 SDK 소유 세션을 종료합니다. 승인 인터럽션(중단 처리)으로 실행이 일시 중지되거나 아직 완료되지 않은 스트리밍 실행이 취소되면, 러너는 대신 소유한 샌드박스 상태를 RunState에 보존하여 동일한 실행을 계속할 수 있도록 합니다.

세션을 직접 생성했다면 직접 종료하세요.

샌드박스 세션 수명 주기 직접 관리

import { run } from '@openai/agents';
import { Manifest, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const manifest = new Manifest();
const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const client = new UnixLocalSandboxClient();
const session = await client.create({ manifest });

try {
  await run(agent, 'First pass.', { sandbox: { session } });
  await run(agent, 'Follow-up pass.', { sandbox: { session } });
} finally {
  await session.close?.();
}

재개 및 스냅샷

샌드박스 상태와 대화 상태는 별개입니다.

• SDK 대화 상태는 result.history, SDK Session, conversationId 또는 previousResponseId에 저장됩니다.
• 샌드박스 상태는 활성 샌드박스 세션, 직렬화된 sessionState, RunState 샌드박스 페이로드 또는 스냅샷에 저장됩니다.

샌드박스 클라이언트를 통해 동일한 백엔드 세션에 다시 연결하려면 sessionState를 사용하세요. 저장된 워크스페이스 내용으로 초기화된 새 세션이 필요하면 스냅샷을 사용하세요.

샌드박스 상태 직렬화 및 재개

import { Manifest } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const manifest = new Manifest();
const client = new UnixLocalSandboxClient({
  snapshot: { type: 'local', baseDir: '/tmp/my-sandbox-snapshots' },
});

const session = await client.create({ manifest });
const state = await client.serializeSessionState?.(session.state);
await session.close?.();

if (state) {
  const restored = await client.resume?.(
    await client.deserializeSessionState!(state),
  );
  await restored?.close?.();
}

RunState는 더 큰 워크플로를 일시 중지하거나 재개할 때 러너가 관리하는 샌드박스 상태도 보존할 수 있습니다. 샌드박스 수명 주기를 직렬화된 실행 외부에서 관리하는 경우 명시적인 sessionState를 사용하세요.

Docker의 경우 동일한 메모리 내 RunState를 재개할 때, SDK가 활성 컨테이너의 신원을 확인하고 현재 매니페스트, 환경, 경로 권한 부여를 다시 검증한 후에만 해당 컨테이너를 재사용할 수 있습니다. 활성 컨테이너 재사용이 불가능하거나 거부되면 Docker는 복원 가능한 스냅샷으로 대체합니다. 직렬화한 후 RunState.fromString(...)으로 재구성한 RunState에는 신뢰할 수 있는 활성 컨테이너 권한 정보가 포함되지 않으므로, 이 경우에도 Docker는 직렬화된 컨테이너 ID에 연결하는 대신 스냅샷에서 복원합니다. 복원 가능한 스냅샷이 구성되어 있지 않으면 검증되지 않은 컨테이너에 연결하는 대신 재개가 실패합니다.

명시적인 baseDir이 없는 로컬 스냅샷의 저장 디렉터리를 변경하려면 OPENAI_AGENTS_SANDBOX_SNAPSHOT_DIR을 설정하세요. 그렇지 않으면 SDK는 macOS에서 ~/Library/Application Support/openai-agents-js/sandbox-snapshots, Windows에서 %LOCALAPPDATA%\openai-agents-js\sandbox-snapshots, 그 외 플랫폼에서 $XDG_STATE_HOME/openai-agents-js/sandbox-snapshots를 사용하며, 해당 위치를 사용할 수 없으면 홈 디렉터리와 임시 디렉터리를 대체 위치로 사용합니다.

매니페스트 구체화

매니페스트 항목은 에이전트가 실행되기 전에 준비됩니다. 실행별 또는 클라이언트 생성 호출별로 구체화 동시 실행 수를 조정할 수 있습니다.

매니페스트 구체화 동시 실행 수 조정

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Repository inspector',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repository before answering.',
});

await run(agent, 'Inspect the repo.', {
  sandbox: {
    client: new UnixLocalSandboxClient(),
    concurrencyLimits: {
      manifestEntries: 4,
      localDirFiles: 16,
    },
  },
});

manifestEntries는 최상위 항목 작업의 병렬 실행 수를 제한합니다. localDirFiles는 localDir() 항목 내부의 파일 복사 동시 실행 수를 제한합니다.

파일시스템 존재 여부 확인

세션이 pathExists()를 구현하는 경우 false는 백엔드에서 해당 경로가 없음을 확인했다는 의미입니다. 권한 오류, I/O 실패, 제공자의 검사 실패는 경로가 없는 것으로 처리되지 않고 제공자 오류로 거부됩니다. 이를 통해 편집기, 매니페스트, 메모리 흐름이 존재하지만 접근할 수 없는 경로를 덮어쓰거나 대체하는 것을 방지합니다.

마운트 및 원격 스토리지

마운트 항목은 노출할 스토리지를 정의하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방법을 정의합니다. 기본 제공 마운트 항목과 범용 전략은 @openai/agents/sandbox에서 가져오세요.

공통 마운트 옵션:

• mountPath: 샌드박스에서 스토리지가 표시되는 위치입니다. 상대 경로는 매니페스트 루트를 기준으로 해석되며, 절대 경로는 그대로 사용됩니다.
• readOnly: 샌드박스가 마운트된 스토리지에 다시 쓰지 못하게 하려면 설정하세요.
• mountStrategy: 마운트 항목과 샌드박스 백엔드 모두에 맞는 전략을 사용하세요.

마운트는 임시 워크스페이스 항목으로 취급됩니다. 스냅샷 및 영속화 흐름에서는 마운트된 원격 스토리지를 저장되는 워크스페이스에 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.

범용 로컬/컨테이너 전략:

전략 또는 패턴	사용하는 경우	참고
inContainerMountStrategy(...)	샌드박스 이미지에서 rclone, mount-s3, blobfuse2와 같은 마운트 명령을 실행할 수 있는 경우입니다.	범용 전략으로 제공되며, 지원 여부는 백엔드에 따라 달라집니다.
dockerVolumeMountStrategy(...)	컨테이너가 시작되기 전에 Docker가 볼륨 드라이버 기반 마운트를 연결해야 하는 경우입니다.	Docker 전용입니다.
localBindMountStrategy()	로컬 백엔드가 절대 로컬 경로를 워크스페이스에 바인딩해야 하는 경우입니다.	허용되는 경우 로컬 워크스페이스 구체화에서 지원됩니다.

백엔드별 지원 범위는 의도적으로 명확히 구분됩니다.

백엔드	마운트 참고 사항
UnixLocalSandboxClient	로컬 워크스페이스 모델을 통해 로컬 바인드 방식 마운트를 지원합니다.
DockerSandboxClient	Docker가 스토리지를 연결할 수 있는 경우 로컬 바인드 마운트와 Docker 볼륨 방식 전략을 지원합니다.
호스팅 제공자	제공자별 전략은 각 제공자의 구현에 포함되어 있습니다. 지원되는 마운트와 필수 설정은 해당 제공자의 문서를 확인하세요.

마운트 항목이 모든 백엔드에서 작동한다고 가정하지 마세요. 클라이언트가 매니페스트 메타데이터, 신원 또는 마운트 동작을 강제할 수 없다면, 매니페스트의 해당 부분을 조용히 무시하는 대신 초기에 실패해야 합니다.

지원되는 호스팅 플랫폼

호스팅 환경이 필요한 경우 일반적으로 동일한 SandboxAgent 정의를 그대로 사용하고 sandbox 실행 옵션에서 샌드박스 클라이언트만 변경하면 됩니다.

호스팅 제공자 구현은 @openai/agents-extensions의 제공자별 하위 경로에서 사용할 수 있습니다. 정확한 환경 변수, 실행 가능한 코드 예제, 포트 동작, PTY 지원, 스냅샷 동작, 정리 동작은 제공자의 문서를 확인하세요.

@openai/agents-extensions를 설치하고 패키지 수준의 피어 의존성을 충족하세요. 각 제공자는 제공자 SDK 패키지나 백엔드 설정을 추가로 요구할 수 있습니다.

클라이언트	가져오기 경로	제공자 요구 사항
BlaxelSandboxClient	@openai/agents-extensions/sandbox/blaxel	npm 피어 의존성: @blaxel/core
CloudflareSandboxClient	@openai/agents-extensions/sandbox/cloudflare	Cloudflare Sandbox 브리지 Worker URL 및 Worker 인증
DaytonaSandboxClient	@openai/agents-extensions/sandbox/daytona	npm 피어 의존성: @daytonaio/sdk
E2BSandboxClient	@openai/agents-extensions/sandbox/e2b	npm 피어 의존성: e2b 또는 @e2b/code-interpreter
ModalSandboxClient	@openai/agents-extensions/sandbox/modal	npm 피어 의존성: modal
VercelSandboxClient	@openai/agents-extensions/sandbox/vercel	npm 피어 의존성: @vercel/sandbox

ModalSandboxClient로 샌드박스를 생성할 때 cpu와 memoryMiB를 사용하여 CPU 및 메모리 예약량을 요청하세요. 상한을 설정하려면 cpuLimit과 memoryLimitMiB를 사용하세요. 이 옵션은 클라이언트 생성자나 실행별 sandbox.options에 설정할 수 있으며, 실행별 값이 생성자의 기본값보다 우선합니다. 모든 값은 양의 유한한 숫자여야 합니다. cpuLimit에는 cpu가 필요하며 그보다 작을 수 없고, memoryLimitMiB에는 memoryMiB가 필요하며 그보다 작을 수 없습니다.

CloudflareSandboxClient는 Cloudflare npm SDK를 가져오지 않습니다. 대신 HTTP를 통해 배포된 Cloudflare Sandbox 브리지 Worker와 통신합니다.

VercelSandboxClient는 생성별 옵션, 생성자 옵션, VERCEL_PROJECT_ID, VERCEL_TEAM_ID, VERCEL_TOKEN 순서의 우선순위로 각 PAT 자격 증명 필드를 결정합니다. 결정된 projectId, teamId, token이 모두 비어 있지 않은 경우에만 자격 증명을 전달합니다. 그렇지 않으면 세 필드를 모두 생략하고, 플랫폼 OIDC나 로컬 제공자 자격 증명을 포함한 인증 처리를 @vercel/sandbox에 맡깁니다. 세션을 직렬화하고 재개할 때 완전하게 결정된 자격 증명은 보존됩니다. 직렬화된 자격 증명은 세 필드가 모두 포함된 하나의 집합으로 취급되며 현재 옵션이나 환경 변수와 혼합되지 않습니다. 불완전한 직렬화 자격 증명은 폐기한 후 현재 구성을 대체 수단으로 사용하여 자격 증명을 결정합니다. 토큰이 직렬화된 세션 상태에 그대로 남아 있으므로 해당 상태를 안전하게 저장하세요.

호스팅형 샌드박스 클라이언트는 제공자별 마운트 전략을 제공합니다. 스토리지 제공자에 가장 적합한 백엔드와 마운트 전략을 선택하세요.

샌드박스 내부에서 헬퍼를 실행하는 자격 증명 포함 마운트는 기본적으로 거부됩니다. 모델이 제어하는 코드가 해당 헬퍼 프로세스의 자격 증명에 접근할 수 있기 때문입니다. 여기에는 지원되는 마운트 필드, 주변 환경의 AWS 또는 GCP 환경 변수, RCLONE_CONFIG_* 값, 워크로드 ID 또는 관리 ID 탐색을 통해 제공되는 자격 증명이 포함됩니다. 자격 증명을 사용하지 않는 rclone 및 mountpoint 헬퍼는 주변 환경이나 메타데이터를 통한 인증을 비활성화하고, 백엔드에서 지원하는 경우 익명 접근을 사용합니다. Docker 볼륨, Modal 클라우드 버킷, Cloudflare 버킷 마운트와 같은 외부 전략이나 제공자 네이티브 전략을 우선 사용하세요.

샌드박스 내부 헬퍼가 필요하면 애플리케이션에서 생성한 매니페스트에서 신뢰할 수 있는 각 실제 적용 마운트 경로에 대해 노출을 승인하세요. 타입이 지정된 마운트 필드를 통해 직접 제공하는 마운트 범위의 자격 증명에는 manifest.withInContainerMountCredentialExposureAcknowledged('mounted/path')가 반환하는 매니페스트를 사용하세요. 주변 환경의 자격 증명, 워크로드 ID 또는 관리 ID, 외부 자격 증명 파일이나 구성 파일에는 manifest.withInContainerMountBroadCredentialExposureAcknowledged('mounted/path')가 반환하는 매니페스트가 필요합니다. 두 종류의 권한을 모두 사용하는 마운트에는 두 승인 모두 필요합니다. 이러한 정확한 경로별 승인은 런타임에서만 유효하며, 매니페스트 초기화 객체나 직렬화된 매니페스트 데이터에서는 절대 허용되지 않습니다. 이 승인은 선택한 헬퍼가 자격 증명을 받도록 허용할 뿐, 해당 자격 증명을 마운트 경로로 제한하지는 않습니다. 따라서 동일한 샌드박스 내에서 모델이 제어하는 다른 코드가 여전히 자격 증명을 획득할 수 있습니다. 샌드박스 범위로 제한된 단기 최소 권한 자격 증명을 사용하세요.

마운트가 참조하는 자격 증명 파일은 직접 또는 심볼릭 링크를 통해 직렬화 가능한 매니페스트 항목을 가리켜서는 안 됩니다. 동적 매니페스트 변경은 세션별로 순차 처리됩니다. 제공자 측에서 변경이 이미 적용되기 시작했을 가능성이 있는 상태에서 권한이 필요한 마운트 전환이나 교체를 위한 마운트 해제가 실패하면, SDK는 불확실한 상태를 재사용하거나 저장하는 대신 해당 세션을 무효화하고 종료합니다.

직렬화된 샌드박스 상태에서는 마운트 자격 증명이 생략되며, 여기에는 샌드박스 내부 마운트 헬퍼가 선택한 주변 환경의 자격 증명도 포함됩니다. 저장된 마운트 토폴로지를 재개하려면 현재의 신뢰할 수 있는 매니페스트가 반드시 필요합니다. 재개 가능한 외부 마운트나 제공자 네이티브 마운트의 경우, SDK는 자격 증명을 제외한 현재 마운트 토폴로지와 저장된 마운트 토폴로지가 일치한 후에만 자격 증명을 복원합니다. 명시적인 sessionState는 가림 처리되지 않은 활성 권한 정보가 현재의 신뢰할 수 있는 매니페스트와 여전히 일치하는 경우에만 기존 제공자 네이티브 마운트에 다시 연결할 수 있습니다. 권한 정보가 가림 처리되거나 교체되거나 제거된 경우에는 새 샌드박스가 필요합니다. 자격 증명이 없는 토폴로지로 분리할 수 없는 불투명한 구성은 재개할 수 없습니다. Runner가 샌드박스 내부 마운트 헬퍼를 사용했던 직렬화된 RunState 항목을 복원할 때는 저장된 세션을 폐기하고 현재의 신뢰할 수 있는 구성으로 새 샌드박스를 생성합니다. 반면 호출자가 제공한 명시적인 sessionState와 제공자를 통한 직접 재개는 컨테이너 내부 마운트 상태를 거부합니다. 이 경우 새 샌드박스를 명시적으로 시작하세요.

백엔드	마운트 참고 사항
Docker	inContainerMountStrategy() 및 dockerVolumeMountStrategy()와 같은 로컬 전략으로 s3Mount(), gcsMount(), r2Mount(), azureBlobMount(), boxMount(), s3FilesMount()를 지원합니다.
ModalSandboxClient	S3, R2 및 HMAC로 인증되는 GCS 마운트 항목에서 ModalCloudBucketMountStrategy를 통한 클라우드 버킷 마운트를 지원합니다.
CloudflareSandboxClient	S3, R2 및 HMAC로 인증되는 GCS 마운트 항목에서 CloudflareBucketMountStrategy를 통한 Cloudflare 버킷 마운트를 지원합니다.
BlaxelSandboxClient	S3, R2 및 GCS 마운트 항목에서 BlaxelCloudBucketMountStrategy를 통한 클라우드 버킷 마운트를 지원합니다. 자격 증명을 포함하는 클라우드 마운트에는 SDK 소유 샌드박스가 필요합니다. SDK가 소유하지 않은 이름이 지정된 샌드박스를 재사용할 때는 자격 증명이 없는 클라우드 마운트나 BlaxelDriveMount 및 BlaxelDriveMountStrategy를 사용하는 영구 Blaxel Drives를 사용할 수 있습니다.
DaytonaSandboxClient	S3, GCS, R2, Azure Blob 및 Box 마운트 항목에서 DaytonaCloudBucketMountStrategy를 통한 rclone 기반 마운트를 지원합니다.
E2BSandboxClient	S3, GCS, R2, Azure Blob 및 Box 마운트 항목에서 E2BCloudBucketMountStrategy를 통한 rclone 기반 마운트를 지원합니다.
VercelSandboxClient	VercelCloudBucketMountStrategy를 통해 생성 시점의 S3 마운트를 지원합니다. 새 코드에서는 각 정확한 마운트 경로에 대해 withInContainerMountCredentialExposureAcknowledged()로 인라인 자격 증명 노출을 승인하세요. 더 이상 권장되지 않는 allowS3CredentialExposure: true 옵션은 이미 배포된 인라인 S3 자격 증명 구성과의 호환성을 위해 계속 허용되지만, 주변 환경의 자격 증명이나 그 밖의 광범위한 권한을 허용하지는 않습니다. 직렬화된 마운트 상태는 직접 재개할 수 없으므로 마운트된 활성 세션을 재사용하세요.

E2B rclone 기반 마운트에서는 사용 가능한 기존 rclone 바이너리가 있으면 SDK가 이를 사용합니다. 그렇지 않으면 SHA-256 체크섬을 검증한 후에만 SDK에서 버전을 고정한 Linux 아카이브를 설치합니다. 지원되지 않는 아키텍처이거나 체크섬 검증에 실패하면 마운트가 중단됩니다.

다음 표는 각 백엔드가 직접 마운트할 수 있는 원격 스토리지 항목을 요약합니다.

백엔드	AWS S3	Cloudflare R2	GCS	Azure Blob Storage	Box	S3 Files
Docker	예	예	예	예	예	예
ModalSandboxClient	예	예	예	아니요	아니요	아니요
CloudflareSandboxClient	예	예	예	아니요	아니요	아니요
BlaxelSandboxClient	예	예	예	아니요	아니요	아니요
DaytonaSandboxClient	예	예	예	예	예	아니요
E2BSandboxClient	예	예	예	예	예	아니요
VercelSandboxClient	예	아니요	아니요	아니요	아니요	아니요

“예”는 백엔드가 해당 스토리지 마운트 유형을 실행할 수 있다는 의미이며, 앞서 설명한 자격 증명 경계를 우회한다는 뜻은 아닙니다. Docker의 dockerVolumeMountStrategy(), Modal 클라우드 버킷 마운트, Cloudflare 버킷 마운트는 마운트 자격 증명을 모델이 제어하는 샌드박스 외부에 유지합니다. Docker의 inContainerMountStrategy()와 Daytona 및 E2B rclone 전략은 자격 증명을 받을 때마다 정확한 경로에 대한 승인이 필요합니다. Box 마운트에는 인증이 필요하므로, Box 권한이 타입이 지정된 마운트 필드를 통해 제공되는지 아니면 외부 자격 증명 파일이나 구성 파일을 통해 제공되는지에 맞는 승인을 선택하세요. Docker S3 Files 마운트는 광범위한 워크로드 ID를 사용하므로 withInContainerMountBroadCredentialExposureAcknowledged()가 필요합니다.

노출된 포트

백엔드에서 지원하는 경우 샌드박스 클라이언트는 resolveExposedPort(port)를 통해 엔드포인트를 노출할 수 있습니다.

클라이언트	동작
UnixLocalSandboxClient	구성된 포트를 127.0.0.1로 해석합니다.
DockerSandboxClient	구성된 컨테이너 포트를 게시하고 해당 호스트 엔드포인트를 확인합니다.

백엔드에서 허용 목록을 강제해야 하는 경우 클라이언트 옵션에 포트를 선언하세요.

포트 노출

import { DockerSandboxClient } from '@openai/agents/sandbox/local';

const client = new DockerSandboxClient({
  image: 'node:22-bookworm-slim',
  exposedPorts: [3000],
});

기능 지원 표

기능	Unix 로컬	Docker
exec_command	지원	지원
PTY write_stdin	지원	지원
apply_patch	지원	워크스페이스 파일 API를 통해 지원
view_image	지원	워크스페이스 파일 API를 통해 지원
명령의 runAs	호스트가 사용자를 확인하고 해당 사용자로 전환할 수 있는 경우 지원	컨테이너/사용자 설정에 따라 제한
로컬 스냅샷	지원	지원
로컬/Docker 마운트	로컬 바인드 방식 지원	바인드 및 Docker 볼륨 방식 지원

로컬 PTY 지원은 SDK 프로세스 내의 소규모 Python 3 브리지를 사용합니다. 이 브리지는 tty: true 세션에서만 사용됩니다. Node.js가 내장 PTY API를 제공하지 않고, SDK가 대화형 stdin, 신호 처리, 종료 상태 보고를 위해 표준 POSIX PTY 동작을 필요로 하기 때문입니다. SDK 코드를 실행하는 환경에 python3를 설치하거나 OPENAI_AGENTS_PYTHON을 Python 3 실행 파일로 설정하세요. 이는 Docker 샌드박스 이미지 내부에 설치된 Python 버전이 있더라도 그와는 별개입니다.

호스팅 제공자의 지원 범위는 제공자에 따라 다릅니다. 정확한 옵션, 환경 변수, 포트 동작, PTY 지원, 스냅샷 동작, 정리 동작은 제공자별 문서를 확인하세요.