Apple컨테이너샌드박스
Apple을 통해 로컬 OCI Linux 컨테이너 내에서 명령을 실행합니다.containerCLI. 공급자는 수명이 긴 컨테이너를 시작하고container exec작업 공간 명령의 경우. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceSandbox 인터페이스.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/apple-container
pnpm add @mastra/apple-container
yarn add @mastra/apple-container
bun add @mastra/apple-container
Apple Silicon Mac에서 macOS 26 이상을 실행하고 Apple의 container CLI가 설치되어 있어야 합니다. Provider를 사용하기 전에 컨테이너 시스템을 시작하세요.
container system start
용법용법에 대한 직접 링크
Workspace에 AppleContainerSandbox를 추가하고 Agent에 할당하세요.
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AppleContainerSandbox } from '@mastra/apple-container'
const workspace = new Workspace({
sandbox: new AppleContainerSandbox({
image: 'node:22-slim',
volumes: {
'/Users/me/project': '/workspace',
},
workingDir: '/workspace',
}),
})
const agent = new Agent({
id: 'dev-agent',
name: 'Dev Agent',
instructions: 'You are a coding assistant working in this workspace.',
model: 'anthropic/claude-sonnet-4-6',
workspace,
})
const response = await agent.generate('Run `node --version`.')
console.log(response.text)
생성자 매개변수생성자 매개변수에 대한 직접 링크
id?:
name?:
container run --name에 전달되는 Apple 컨테이너 이름입니다. [a-zA-Z0-9_.-] 이외의 문자는 -로 대체되며, 결과가 영숫자로 시작하지 않으면 접두사가 추가됩니다.image?:
command?:
env?:
volumes?:
mounts?:
container run --mount 사양입니다.network?:
publishedPorts?:
--publish로 전달되는 포트 게시 사양입니다.publishedSockets?:
--publish-socket으로 전달되는 소켓 게시 사양입니다.cpus?:
memory?:
platform?:
arch?:
os?:
rosetta?:
readonlyRootfs?:
ssh?:
init?:
virtualization?:
capAdd?:
capDrop?:
tmpfs?:
--tmpfs로 전달되는 tmpfs 대상 경로입니다(예: /tmp).dns?:
dnsSearch?:
noDns?:
labels?:
workingDir?:
timeout?:
deleteOnDestroy?:
containerBinary?:
instructions?:
속성속성에 대한 직접 링크
id:
name:
provider:
status:
containerId:
환경변수환경변수에 대한 직접 링크
env를 사용하여 컨테이너 수준에서 환경 변수를 설정합니다. 명령별 환경 변수는 executeCommand 옵션을 통해서도 전달할 수 있습니다.
const sandbox = new AppleContainerSandbox({
image: 'node:22-slim',
env: {
NODE_ENV: 'development',
},
})
await sandbox.executeCommand('node', ['-e', 'console.log(process.env.TASK_ID)'], {
env: { TASK_ID: '42' },
})
바인드 마운트바인드 마운트에 대한 직접 링크
다음을 사용하여 호스트 디렉터리를 컨테이너에 마운트합니다.volumes option:
const sandbox = new AppleContainerSandbox({
image: 'node:22-slim',
volumes: {
'/Users/me/project': '/workspace/project',
'/Users/me/.npm': '/root/.npm',
},
})
바인드 마운트는 컨테이너 생성 시 적용됩니다. 샌드박스가 시작되기 전에 호스트 경로가 존재해야 합니다.
리소스 및 플랫폼 옵션리소스 및 플랫폼 옵션에 대한 직접 링크
Apple 컨테이너 CLI 옵션은 생성자를 통해 전달될 수 있습니다.
const sandbox = new AppleContainerSandbox({
image: 'node:22-slim',
volumes: {
'/Users/me/project': '/workspace',
},
cpus: 2,
memory: '2G',
platform: 'linux/arm64',
readonlyRootfs: true,
tmpfs: ['/tmp'],
})
이러한 옵션은 새 컨테이너가 생성될 때만 적용됩니다. Sandbox가 동일한 이름을 가진 기존 컨테이너에 다시 연결되면 변경된 런타임 옵션을 적용하기 위해 Sandbox를 삭제한 후 다시 생성하세요.
Apple의 --tmpfs는 /tmp와 같은 컨테이너 경로만 허용하며, /tmp:rw,size=256m과 같은 Docker 스타일 옵션 사양은 허용하지 않습니다.
readonlyRootfs를 활성화할 때는 workingDir이 이미지 또는 바인드 마운트에서 제공하는 경로를 가리키는지 확인하세요. 쓰기 가능한 tmpfs도 지원됩니다.
보안 Model보안 Model에 대한 직접 링크
AppleContainerSandbox는 호스트의 Apple container 서비스를 통해 로컬 컨테이너를 실행합니다. 생성자 옵션은 신뢰할 수 있는 서버 측 구성으로 취급하세요.
volumes,mounts,publishedSockets는 호스트 경로를 컨테이너화된 코드에 노출할 수 있습니다.publishedPorts는 호스트 또는 네트워크에서 컨테이너 내 서비스를 노출할 수 있습니다. 로컬 접근만 허용하려면127.0.0.1에 바인딩하세요.ssh는 호스트 SSH Agent 소켓을 전달합니다.capAdd와virtualization은 컨테이너화된 코드가 수행할 수 있는 작업의 범위를 확장할 수 있습니다.containerBinary는 신뢰할 수 있는 코드를 위한 생성자 전용 이스케이프 해치이며, 직렬화 가능한 편집기 Provider 스키마에는 포함되지 않습니다. 워크로드에 필요한 가장 좁은 마운트와 기능을 사용하세요. 기존 컨테이너는 샌드박스 ID에 대한 Mastra 소유권 레이블이 있는 경우에만 다시 연결됩니다. 이 공급자가 만든 컨테이너에는 config-hash 레이블도 포함되어 있습니다. 해당 레이블이 있는 경우 이미지, 명령, 마운트, 포트, 기능 또는 작업 디렉터리와 같은 변경할 수 없는 런타임 옵션이 변경되면 다시 연결이 실패합니다.
제한사항제한사항에 대한 직접 링크
AppleContainerSandbox는 executeCommand()를 사용하여 포그라운드 Workspace 명령 실행을 구현합니다. 백그라운드 프로세스나 LSP 세션을 위한 SandboxProcessManager는 아직 제공하지 않습니다.
명령 시간 초과는 컨테이너 내부에서 적용되므로 시간 초과된 명령은 컨테이너 런타임에 의해 정리됩니다. 중단 신호는 호스트 CLI 대기 경로를 취소하므로 컨테이너 내 정리가 중요한 경우 명령 시간 초과 대신 사용해서는 안 됩니다.
재연결재연결에 대한 직접 링크
AppleContainerSandbox는 구성된 이름의 컨테이너를 검사하여 다시 연결합니다. start()가 호출되면 다음과 같이 동작합니다.
- 실행 중인 컨테이너는 재사용됩니다.
- 중지된 컨테이너가 다시 시작됩니다.
- 구성된 이미지에서 누락된 컨테이너가 생성됩니다.
- 이름이 구성되어 있지만 Mastra 소유권 라벨이 일치하지 않는 컨테이너는 관리되지 않고 실패합니다.
- 변경할 수 없는 런타임 옵션과 일치하지 않는 구성 해시 레이블이 있는 Mastra 소유 컨테이너는 재사용되지 않고 실패합니다.
const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox.start()
const sandbox2 = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox2.start()
편집자 Provider편집자 Provider에 대한 직접 링크
저장된 Sandbox 구성을 하이드레이션하려면 MastraEditor에 Provider를 등록하세요.
import { MastraEditor } from '@mastra/editor'
import { appleContainerSandboxProvider } from '@mastra/apple-container'
const editor = new MastraEditor({
sandboxes: {
[appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
},
})