E2B샌드박스
격리된 상태에서 명령을 실행합니다.E2B클라우드 샌드박스. 클라우드 스토리지 마운트를 지원하여 안전한 임시 환경을 제공합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceSandbox 인터페이스.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/e2b
pnpm add @mastra/e2b
yarn add @mastra/e2b
bun add @mastra/e2b
용법용법에 대한 직접 링크
Workspace에 E2BSandbox를 추가하고 Agent에 할당합니다:
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { E2BSandbox } from '@mastra/e2b'
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
timeout: 60_000, // 60 second timeout (default: 5 minutes)
}),
})
const agent = new Agent({
id: 'dev-agent',
name: 'dev-agent',
model: 'anthropic/claude-opus-4-7',
workspace,
})
생성자 매개변수생성자 매개변수에 대한 직접 링크
apiKey?:
timeout?:
template?:
env?:
id?:
domain?:
apiUrl?:
accessToken?:
metadata?:
instructions?:
getInstructions()가 반환하는 사용자 지정 지침입니다. 문자열은 기본값을 완전히 대체합니다. 함수는 기본값을 전달받으며 요청별로 이를 확장하거나 사용자 지정할 수 있습니다. 지침을 완전히 표시하지 않으려면 빈 문자열을 전달합니다.속성속성에 대한 직접 링크
id:
name:
provider:
status:
processes:
백그라운드 프로세스백그라운드 프로세스에 대한 직접 링크
E2BSandbox에는 백그라운드 프로세스를 생성하고 관리하는 내장 프로세스 관리자가 포함되어 있습니다. 프로세스는 background: true가 지정된 E2B SDK의 commands.run()을 사용하여 E2B 클라우드 Sandbox에서 실행됩니다.
const sandbox = new E2BSandbox({ id: 'dev-sandbox' })
await sandbox.start()
// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
env: { PORT: '3000' },
onStdout: data => console.log(data),
})
// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
E2B 프로세스 관리자는 외부에서 생성되었거나 재연결 전에 생성된 프로세스에 대한 재연결을 지원합니다. 기존 프로세스에 연결하려면 PID를 사용해 get(pid)를 호출합니다:
const handle = await sandbox.processes.get(existingPid)
if (handle) {
console.log(handle.stdout)
}
전체 API는 SandboxProcessManager 레퍼런스를 참조하세요.
클라우드 스토리지 마운트클라우드 스토리지 마운트에 대한 직접 링크
E2B 샌드박스는 S3, GCS 및 Azure Blob 파일 시스템을 마운트할 수 있으므로 클라우드 스토리지를 샌드박스 내부의 로컬 디렉터리로 액세스할 수 있습니다. 이는 다음과 같은 경우에 유용합니다.
- 클라우드 버킷에 저장된 대규모 데이터 세트 처리
- 출력 파일을 클라우드 스토리지에 직접 쓰기
- 샌드박스 세션 간 데이터 공유
마운트 구성 사용마운트 구성 사용에 대한 직접 링크
파일 시스템을 마운트하는 가장 간단한 방법은 작업 공간을 이용하는 것입니다.mounts config:
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'
const workspace = new Workspace({
mounts: {
'/s3-data': new S3Filesystem({
bucket: 'my-s3-bucket',
region: 'us-east-1',
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
}),
'/gcs-data': new GCSFilesystem({
bucket: 'my-gcs-bucket',
projectId: 'my-project',
credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
}),
},
sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
Sandbox가 시작되면 파일 시스템이 지정된 경로에 자동으로 마운트됩니다. Sandbox에서 실행되는 코드는 /s3-data 및 /gcs-data의 파일에 로컬 디렉터리처럼 액세스할 수 있습니다.
장착 작동 방식장착 작동 방식에 대한 직접 링크
E2B 샌드박스는 FUSE(사용자 공간의 파일 시스템)를 사용하여 클라우드 스토리지를 마운트합니다.
E2B 샌드박스는 마운팅을 사용할 때 필요한 FUSE Tool을 자동으로 설치합니다. 최상의 성능을 위해서는 Tool이 설치된 사용자 정의 템플릿을 미리 구축하십시오.
맞춤 템플릿맞춤 템플릿에 대한 직접 링크
기본적으로 템플릿을 지정하지 않으면 E2BSandbox는 S3 마운트 지원을 위해 s3fs가 설치된 템플릿을 자동으로 빌드합니다. 이 템플릿은 캐시되어 Sandbox 인스턴스 간에 재사용됩니다.
GCS 마운트의 경우 gcsfuse가 아직 없으면 마운트할 때 자동으로 설치됩니다. Tool을 추가하거나 콜드 스타트를 단축하려면 사용자 지정 템플릿을 사용하세요.
기존 템플릿 사용기존 템플릿 사용에 대한 직접 링크
사전 구축된 템플릿이 있는 경우 해당 ID를 전달합니다.
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
template: 'my-custom-template',
}),
})
기본 템플릿 사용자 정의기본 템플릿 사용자 정의에 대한 직접 링크
기본 마운트 지원 템플릿을 사용자 지정하는 함수를 전달합니다. 함수는 TemplateBuilder를 전달받아 수정된 템플릿을 반환해야 합니다:
const workspace = new Workspace({
sandbox: new E2BSandbox({
template: base =>
base
.aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
.pipInstall(['pandas', 'numpy'])
.npmInstall(['sharp']),
}),
})
템플릿 빌더는 다음과 같은 작업을 통해 메소드 체이닝을 지원합니다.
aptInstall(packages)- 시스템 패키지 설치pipInstall(packages)- Python 패키지 설치npmInstall(packages)- Node.js 패키지 설치runCmd(command)- 쉘 명령 실행setEnvs(vars)- 환경변수 설정copy(src, dest)- 템플릿에 파일 복사
사용 가능한 메서드의 전체 목록은 E2B 템플릿 문서를 참조하세요.
사전 구축 템플릿사전 구축 템플릿에 대한 직접 링크
기본 템플릿은 처음 사용할 때 작성되고 캐시됩니다. 더 빠른 콜드 스타트를 원하거나 GCS 지원을 포함하려면 템플릿을 사전 빌드할 수 있습니다.
import { createDefaultMountableTemplate } from '@mastra/e2b'
import { Template } from 'e2b'
// Get the default mountable template (includes s3fs)
const { template, id } = createDefaultMountableTemplate()
// Build and save to E2B
const result = await Template.build(template, id)
console.log('Template ID:', result.templateId)
// Use this ID in your E2BSandbox config for instant startup
const sandbox = new E2BSandbox({
template: result.templateId,
})
GCS 콜드 스타트를 단축하려면 사용자 지정 템플릿에 gcsfuse를 미리 설치합니다:
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
template: base => base.aptInstall(['gcsfuse']),
}),
})
이는 선택 사항입니다. gcsfuse가 없으면 마운트할 때 자동으로 설치됩니다.
코드 모드와 함께 사용코드 모드와 함께 사용에 대한 직접 링크
코드 모드를 사용하면 Agent가 Tool을 조율하는 단일 TypeScript 프로그램을 작성할 수 있습니다. E2B는 원격 마이크로 VM에서 해당 프로그램을 실행하므로, 호스트가 아닌 Sandbox 파일 시스템에 프로그램을 쓰는 전송 계층이 필요합니다. @mastra/e2b는 이를 위한 E2BCodeModeTransport를 제공합니다. 이를 createCodeMode의 두 번째 인수로 전달합니다:
import { createCodeMode } from '@mastra/core/tools'
import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'
const { tool, instructions } = createCodeMode(
{
tools: { getWeather, getForecast },
sandbox: new E2BSandbox({ timeout: 60_000 }),
},
new E2BCodeModeTransport(),
)
E2BCodeModeTransport는 Sandbox가 실행 중이 아니면 자동으로 시작하고, Sandbox의 Node 버전과 관계없이 작동하도록 esbuild를 사용해 호스트에서 TypeScript를 변환한 다음 VM 내부에서 node로 실행하며, 이후 프로그램 파일을 정리합니다. @mastra/core의 기본 StdioCodeModeTransport는 LocalSandbox처럼 호스트 파일 시스템을 공유하는 Sandbox에서만 작동합니다.