샌드박스프로세스 관리자

추가된 항목: @mastra/core@1.7.0

샌드박스에서 백그라운드 프로세스를 관리하기 위한 추상 기본 클래스입니다. 프로세스를 생성하고, 나열하고, PID로 핸들을 가져오고, 종료하는 방법을 제공합니다.

BlaxelSandbox, DaytonaSandbox, E2BSandbox, ModalSandbox, 그리고LocalSandbox모두 내장된 프로세스 관리자를 포함합니다. 사용자 정의 샌드박스 공급자를 구축하지 않는 한 이 클래스를 직접 인스턴스화할 필요는 없습니다.

사용예

샌드박스를 통해 프로세스 관리자에 액세스합니다.processes property:

src/mastra/index.ts

import { LocalSandbox } from '@mastra/core/workspace'

const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
await sandbox.start()

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

// List all tracked processes
const procs = await sandbox.processes.list()

// Get a handle by PID
const proc = await sandbox.processes.get(handle.pid)

// Kill a process
await sandbox.processes.kill(handle.pid)

행동 양식

spawn(command, options?)

백그라운드 프로세스를 생성합니다. 프로세스가 완료될 때까지 기다리지 않고 즉시 ProcessHandle을 반환합니다.

const handle = await sandbox.processes.spawn('npm run dev', {
  cwd: '/app',
  env: { NODE_ENV: 'development' },
  onStdout: data => console.log(data),
})

매개변수:

command:

string

실행할 명령입니다. 셸에서 해석됩니다.

options?:

SpawnProcessOptions

생성된 프로세스의 선택적 설정입니다.

SpawnProcessOptions

timeout?:

number

제한 시간(밀리초)입니다. 초과하면 프로세스를 종료합니다.

env?:

NodeJS.ProcessEnv

프로세스의 환경 변수입니다.

cwd?:

string

프로세스의 작업 디렉터리입니다.

onStdout?:

(data: string) => void

stdout 청크의 콜백입니다. 데이터가 도착할 때 호출됩니다.

onStderr?:

(data: string) => void

stderr 청크의 콜백입니다. 데이터가 도착할 때 호출됩니다.

abortSignal?:

AbortSignal

프로세스를 중단하는 신호입니다. 중단되면 프로세스가 종료됩니다.

보고: Promise<ProcessHandle>

list()

추적된 모든 프로세스를 나열합니다. PID, 실행 상태 및 종료 코드를 포함하여 각 프로세스에 대한 정보를 반환합니다.

const procs = await sandbox.processes.list()
for (const proc of procs) {
  console.log(proc.pid, proc.running, proc.exitCode)
}

보고: Promise<ProcessInfo[]>

get(pid)

PID로 프로세스 핸들을 가져옵니다. 프로세스를 찾을 수 없거나 이미 해제된 경우 undefined를 반환합니다.

const handle = await sandbox.processes.get(1234)
if (handle) {
  console.log(handle.stdout)
  await handle.kill()
}

보고: Promise<ProcessHandle | undefined>

kill(pid)

PID로 프로세스를 종료합니다. 반환하기 전에 프로세스가 종료될 때까지 기다립니다. 프로세스를 종료했으면 true, 찾지 못했으면 false를 반환합니다.

const killed = await sandbox.processes.kill(handle.pid)

보고: Promise<boolean>

ProcessInfo

추적된 프로세스에 대한 정보(다음에서 반환)list().

pid:

number

프로세스 ID입니다.

command?:

string

실행된 명령입니다.

running:

boolean

프로세스가 아직 실행 중인지 여부입니다.

exitCode?:

number

프로세스가 완료된 경우의 종료 코드입니다.

---

ProcessHandle

생성된 백그라운드 프로세스를 처리합니다. 출력을 읽고, stdin을 보내고, 완료를 기다리고, 프로세스를 종료하는 메서드를 제공합니다.

ProcessHandle 인스턴스를 직접 생성하지 않습니다. spawn()과 get()이 이를 반환합니다.

사용예

const handle = await sandbox.processes.spawn('npm run dev', {
  onStdout: data => console.log(data),
})

// Read accumulated output
console.log(handle.pid)
console.log(handle.stdout)
console.log(handle.stderr)
console.log(handle.exitCode) // undefined while running

// Wait for completion
const result = await handle.wait()

// Send stdin
await handle.sendStdin('input data\n')

// Kill the process
await handle.kill()

속성

pid:

number

프로세스 ID입니다.

stdout:

string

현재까지 누적된 stdout 출력입니다.

stderr:

string

현재까지 누적된 stderr 출력입니다.

exitCode:

number | undefined

종료 코드입니다. 프로세스가 아직 실행 중이면 undefined입니다.

command:

string | undefined

생성된 명령입니다. 프로세스 관리자가 자동으로 설정합니다.

reader:

Readable

stdout의 읽기 가능 스트림입니다. stdio를 통해 통신하는 LSP 또는 JSON-RPC 같은 프로토콜에 유용합니다.

writer:

Writable

stdin으로 연결되는 쓰기 가능 스트림입니다. stdio를 통해 통신하는 LSP 또는 JSON-RPC 같은 프로토콜에 유용합니다.

행동 양식

wait(options?)

프로세스가 종료될 때까지 기다린 후 결과를 반환합니다. 기다리는 동안 출력을 스트리밍하려면 선택적으로 onStdout/onStderr 콜백을 전달합니다. 콜백은 wait()가 완료되면 자동으로 제거됩니다.

// Simple wait
const result = await handle.wait()
console.log(result.success, result.exitCode, result.stdout)

// Wait with streaming
const result = await handle.wait({
  onStdout: data => process.stdout.write(data),
  onStderr: data => process.stderr.write(data),
})

매개변수:

options?:

WaitOptions

대기에 사용할 선택적 설정입니다.

WaitOptions

onStdout?:

(data: string) => void

대기 중 stdout 청크를 처리하는 콜백입니다.

onStderr?:

(data: string) => void

대기 중 stderr 청크를 처리하는 콜백입니다.

보고: Promise<CommandResult>

그만큼CommandResult object contains:

success:

boolean

종료 코드가 0이면 true입니다.

exitCode:

number

숫자 형식의 종료 코드입니다.

stdout:

string

전체 stdout 출력입니다.

stderr:

string

전체 stderr 출력입니다.

executionTimeMs:

number

실행 시간(밀리초)입니다.

timedOut?:

boolean

제한 시간 초과로 프로세스가 종료되었으면 true입니다.

killed?:

boolean

신호로 프로세스가 종료되었으면 true입니다.

kill()

프로세스를 종료합니다. 프로세스를 종료했으면 true, 이미 종료된 상태였으면 false를 반환합니다.

const killed = await handle.kill()

보고: Promise<boolean>

sendStdin(data)

프로세스의 stdin으로 데이터를 보냅니다. 프로세스가 이미 종료되었거나 stdin을 사용할 수 없는 경우 발생합니다.

await handle.sendStdin('console.log("hello")\n')

보고: Promise<void>

스트림 상호 운용성

ProcessHandle은 LSP 또는 JSON-RPC 같은 Node.js 스트림 기반 프로토콜과 통합할 수 있도록 reader 및 writer 속성을 노출합니다.

import {
  createMessageConnection,
  StreamMessageReader,
  StreamMessageWriter,
} from 'vscode-jsonrpc/node'

const handle = await sandbox.processes.spawn('typescript-language-server --stdio')

const connection = createMessageConnection(
  new StreamMessageReader(handle.reader),
  new StreamMessageWriter(handle.writer),
)
connection.listen()

사용자 정의 프로세스 관리자 구축

사용자 지정 Sandbox Provider용 프로세스 관리자를 구축하려면 SandboxProcessManager를 확장하고 spawn()과 list()를 구현합니다. 기본 클래스가 메서드를 ensureRunning()으로 자동 래핑하므로 모든 프로세스 작업 전에 Sandbox가 시작됩니다.

import { SandboxProcessManager, ProcessHandle } from '@mastra/core/workspace'
import type { ProcessInfo, SpawnProcessOptions } from '@mastra/core/workspace'

class MyProcessManager extends SandboxProcessManager<MySandbox> {
  async spawn(command: string, options: SpawnProcessOptions = {}): Promise<ProcessHandle> {
    // Your spawn implementation
    const handle = new MyProcessHandle(/* ... */)
    this._tracked.set(handle.pid, handle)
    return handle
  }

  async list(): Promise<ProcessInfo[]> {
    return Array.from(this._tracked.values()).map(handle => ({
      pid: handle.pid,
      running: handle.exitCode === undefined,
      exitCode: handle.exitCode,
    }))
  }
}

MastraSandbox의 processes 옵션을 통해 프로세스 관리자를 Sandbox에 전달합니다.

class MySandbox extends MastraSandbox {
  constructor() {
    super({
      name: 'MySandbox',
      processes: new MyProcessManager(),
    })
  }
}

프로세스 관리자가 제공되면 MastraSandbox가 spawn() + wait()를 사용하는 기본 executeCommand 구현을 자동으로 생성하므로 둘 다 구현할 필요가 없습니다.

관련된

• 모래 상자
• WorkspaceSandbox 인터페이스
• 로컬샌드박스 참조
• E2B샌드박스 참조
• Daytona샌드박스 참조