본문으로 건너뛰기

모달샌드박스

격리된 상태에서 명령을 실행합니다.Modal클라우드 샌드박스. Modal의 인프라가 지원되는 안전하고 임시적인 환경을 제공합니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceSandbox 인터페이스.

설치
설치에 대한 직접 링크

npm install @mastra/modal

용법
용법에 대한 직접 링크

Workspace에 ModalSandbox를 추가하고 Agent에 할당합니다:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ModalSandbox } from '@mastra/modal'

const workspace = new Workspace({
  sandbox: new ModalSandbox({
    id: 'dev-sandbox',
    baseImage: 'ubuntu:22.04',
    timeoutMs: 60_000,
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

입증
입증에 대한 직접 링크

환경 변수 또는 생성자 옵션을 통해 모달 자격 증명을 설정합니다.

MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...

또는 직접 전달하세요.

const sandbox = new ModalSandbox({
  tokenId: process.env.MODAL_TOKEN_ID,
  tokenSecret: process.env.MODAL_TOKEN_SECRET,
})

다음에서 자격 증명을 받으세요.Modal dashboard.

생성자 매개변수
생성자 매개변수에 대한 직접 링크

id?:

string
= 자동 생성
이 Sandbox의 고유 식별자/이름입니다. 이후 start() 호출에서 Sandbox에 다시 연결할 수 있도록 Modal Sandbox 이름으로 사용됩니다.

appName?:

string
= 'mastra'
Sandbox와 연결할 Modal App 이름입니다.

baseImage?:

string
= 'ubuntu:22.04'
Sandbox에 사용할 Docker 이미지입니다.

timeoutMs?:

number
= 300000(5분)
밀리초 단위의 최대 실제 수명입니다. 활동 여부와 관계없이 이 시간이 만료되면 Sandbox가 종료됩니다. Modal의 최대값은 24시간(86_400_000)입니다.

env?:

Record<string, string>
생성 시 Sandbox에 포함되는 환경 변수입니다.

workdir?:

string
Sandbox 내부의 기본 작업 디렉터리입니다.

tokenId?:

string
Modal 토큰 ID입니다. MODAL_TOKEN_ID 환경 변수를 대신 사용할 수 있습니다.

tokenSecret?:

string
Modal 토큰 비밀 값입니다. MODAL_TOKEN_SECRET 환경 변수를 대신 사용할 수 있습니다.

instructions?:

string | function
getInstructions()에서 반환되는 사용자 지정 지침입니다. 기본값을 완전히 대체하려면 문자열을 전달하고, 확장하려면 함수를 전달합니다.

onStart?:

function
Sandbox가 실행 상태에 도달한 후 호출되는 수명 주기 훅입니다.

onStop?:

function
Sandbox가 중지되기 전에 호출되는 수명 주기 훅입니다.

onDestroy?:

function
Sandbox가 폐기되기 전에 호출되는 수명 주기 훅입니다.

속성
속성에 대한 직접 링크

id:

string
Sandbox 인스턴스 식별자입니다.

name:

string
Provider 이름('ModalSandbox')

provider:

string
Provider 식별자('modal')

status:

ProviderStatus
'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

modal:

Sandbox
기반 Modal Sandbox 인스턴스입니다. Sandbox가 시작되지 않았으면 SandboxNotReadyError를 발생시킵니다.

processes:

ModalProcessManager
백그라운드 프로세스 관리자입니다. SandboxProcessManager 레퍼런스를 참조하세요.

샌드박스 수명주기
샌드박스 수명주기에 대한 직접 링크

  • _start(): 실행 중인 기존 Sandbox에 다시 연결을 시도합니다. 찾지 못하면 최신 스냅샷(이전 _stop()에서 생성된 스냅샷이 있는 경우) 또는 baseImage에서 Sandbox를 생성합니다.
  • _stop(): 파일 시스템의 스냅샷을 생성한 다음 Sandbox를 종료합니다. 스냅샷은 이후 시작에 사용할 수 있도록 동일한 인스턴스의 Memory에 보관됩니다.
  • _destroy(): Sandbox를 종료하고 모든 스냅샷을 삭제합니다.
const sandbox = new ModalSandbox({
  id: 'dev-sandbox',
  baseImage: 'ubuntu:22.04',
  timeoutMs: 300_000,
})

await sandbox._start()
await sandbox.processes.spawn('npm install')
await sandbox._stop()
await sandbox._start()

백그라운드 프로세스
백그라운드 프로세스에 대한 직접 링크

ModalSandbox에는 백그라운드 프로세스를 생성하고 관리하는 내장 프로세스 관리자가 포함되어 있습니다. 각 spawn() 호출은 Modal SDK의 Sandbox.exec() API를 통해 새 ContainerProcess를 생성합니다.

const sandbox = new ModalSandbox({ id: 'dev-sandbox' })
await sandbox._start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node script.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Wait for the process to complete
const result = await handle.wait()
console.log(result.exitCode)

// Kill the process
await handle.kill()
노트

sendStdin()지원되지 않습니다. Modal JS SDK는 stdin을 노출하지 않습니다.Sandbox.exec().

전체 API는 SandboxProcessManager 레퍼런스를 참조하세요.

On this page