DaytonaSandbox

分離された Daytona クラウド Sandbox でコマンドを実行します。複数のランタイム、リソース設定、ボリューム、スナップショット、出力ストリーミング、Sandbox への再接続、Filesystem のマウント（S3、GCS）、ネットワーク分離に対応します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。

インストール

npm

npm install @mastra/daytona

pnpm

pnpm add @mastra/daytona

Yarn

yarn add @mastra/daytona

Bun

bun add @mastra/daytona

Daytona API キーは、次の3つの方法のいずれかで設定します。

シェルでエクスポート

export DAYTONA_API_KEY=your-api-key

.env ファイル

DAYTONA_API_KEY=your-api-key

コンストラクター

new DaytonaSandbox({ apiKey: 'your-api-key' })

使用方法

Workspace に DaytonaSandbox を追加して Agent に割り当てます。

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { DaytonaSandbox } from '@mastra/daytona'

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    language: 'typescript',
    timeout: 120_000,
  }),
})

const agent = new Agent({
  id: 'code-agent',
  name: 'Code Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate(
  'Print "Hello, world!" and show the current working directory.',
)

console.log(response.text)
// I'll run both commands simultaneously!
//
// Here are the results:
//
// 1. **Hello, world!** — Successfully printed the message.
// 2. **Current Working Directory** — `/home/daytona`
//
// Both commands ran in parallel and completed successfully!

スナップショットを使用する

ビルド済みのスナップショットを使用すると、環境設定の時間を省けます。

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    snapshot: 'my-snapshot-id',
    timeout: 60_000,
  }),
})

リソースを指定したカスタムイメージ

リソース割り当てを指定してカスタム Docker イメージを使用します。

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    image: 'node:20-slim',
    resources: { cpu: 2, memory: 4, disk: 6 },
    language: 'typescript',
  }),
})

一時的な Sandbox

単発タスクでは、停止時に Sandbox を直ちに削除できます。

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    ephemeral: true,
    language: 'python',
  }),
})

出力のストリーミング

onStdout と onStderr コールバックを介して、コマンド出力をリアルタイムでストリーミングします。

await sandbox.executeCommand('bash', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
  onStdout: chunk => process.stdout.write(chunk),
  onStderr: chunk => process.stderr.write(chunk),
})

どちらのコールバックも任意で、個別に使用できます。

再接続

同じ id を指定して既存の Sandbox に再接続します。ファイルと状態を維持したまま Sandbox が再開されます。

const sandbox = new DaytonaSandbox({ id: 'my-persistent-sandbox' })

// First session
await sandbox._start()
await sandbox.executeCommand('sh', ['-c', 'echo "session 1" > /tmp/state.txt'])
await sandbox._stop()

// Later — reconnects to the same sandbox
const sandbox2 = new DaytonaSandbox({ id: 'my-persistent-sandbox' })
await sandbox2._start()
const result = await sandbox2.executeCommand('cat', ['/tmp/state.txt'])
console.log(result.stdout) // "session 1"

Sandbox が停止またはアーカイブ済みの場合は自動的に再起動します。使用不能な状態（破棄済み、エラー）の場合は、代わりに新しい Sandbox を作成します。

Filesystem のマウント

S3 または GCS バケットを Sandbox 内のローカルディレクトリとしてマウントします。

Workspace の mounts 設定を使用する

最も簡単な方法では、Sandbox の起動時に Filesystem が自動的にマウントされます。

import { Workspace } from '@mastra/core/workspace'
import { DaytonaSandbox } from '@mastra/daytona'
import { GCSFilesystem } from '@mastra/gcs'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  mounts: {
    '/s3-data': new S3Filesystem({
      bucket: process.env.S3_BUCKET!,
      region: 'auto',
      accessKeyId: process.env.S3_ACCESS_KEY_ID,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
      endpoint: process.env.S3_ENDPOINT, // e.g. https://<account-id>.r2.cloudflarestorage.com
    }),
    '/gcs-data': new GCSFilesystem({
      bucket: process.env.GCS_BUCKET!,
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
    }),
  },
  sandbox: new DaytonaSandbox({ language: 'python' }),
})

Workspace の起動時に、Filesystem が指定されたパスへ自動的にマウントされます。Sandbox 内で実行されるコードは、/s3-data と /gcs-data のファイルへローカルディレクトリと同様にアクセスできます。

sandbox.mount() を使用する

Sandbox の起動後、任意の時点で手動マウントできます。

S3

import { S3Filesystem } from '@mastra/s3'

await sandbox.mount(
  new S3Filesystem({
    bucket: process.env.S3_BUCKET!,
    region: 'us-east-1',
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  }),
  '/data',
)

S3 互換（Cloudflare R2、MinIO）

import { S3Filesystem } from '@mastra/s3'

await sandbox.mount(
  new S3Filesystem({
    bucket: process.env.S3_BUCKET!,
    region: 'auto',
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    endpoint: process.env.S3_ENDPOINT, // e.g. https://<account-id>.r2.cloudflarestorage.com
  }),
  '/data',
)

GCS

import { GCSFilesystem } from '@mastra/gcs'

await sandbox.mount(
  new GCSFilesystem({
    bucket: process.env.GCS_BUCKET!,
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
  }),
  '/data',
)

ネットワーク分離

外向きのネットワークアクセスを制限します。

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    networkBlockAll: true,
    networkAllowList: '10.0.0.0/8,192.168.0.0/16',
  }),
})

パッケージレジストリやホスト型 API など、IP アドレスが変わるサービスには domainAllowList を使用します。

const workspace = new Workspace({
  sandbox: new DaytonaSandbox({
    networkBlockAll: true,
    domainAllowList: 'registry.npmjs.org,*.githubusercontent.com',
  }),
})

どちらの許可リストも Sandbox の作成時に適用され、clone() でも維持されます。Sandbox の起動後にポリシーを変更するには、基盤となる Daytona Sandbox を使用します。

await sandbox.instance.updateNetworkSettings({
  domainAllowList: 'api.example.com',
})

コンストラクターパラメーター

id?:

string

= Auto-generated

この Sandbox インスタンスの一意な識別子。

apiKey?:

string

認証用の Daytona API キー。未指定の場合は環境変数 DAYTONA_API_KEY を使用します。

apiUrl?:

string

Daytona API エンドポイント。未指定の場合は環境変数 DAYTONA_API_URL を使用します。

target?:

string

Runner リージョン。未指定の場合は環境変数 DAYTONA_TARGET を使用します。

timeout?:

number

= 300000 (5 minutes)

デフォルトの実行タイムアウト（ミリ秒）。

language?:

'typescript' | 'javascript' | 'python'

= 'typescript'

Sandbox のランタイム言語。

snapshot?:

string

Sandbox の作成元となるビルド済みスナップショット ID。image より優先されます。

image?:

string

Sandbox の作成に使用する Docker イメージ。設定するとイメージベースで作成されます。resources と併用できます。snapshot が設定されている場合は無視されます。

resources?:

{ cpu?: number; memory?: number; disk?: number }

Sandbox のリソース割り当て（CPU コア数、GiB 単位のメモリとディスク）。image が設定されている場合にのみ使用されます。

env?:

Record<string, string>

= {}

Sandbox に設定する環境変数。

labels?:

Record<string, string>

= {}

カスタムメタデータラベル。

name?:

string

= Sandbox id

Sandbox の表示名。

user?:

string

= 'daytona'

コマンドを実行する OS ユーザー。

public?:

boolean

= false

ポートプレビューを公開するかどうか。

ephemeral?:

boolean

= false

停止時に Sandbox を直ちに削除するかどうか。

autoStopInterval?:

number

= 15

自動停止までの時間（分）。無効にするには 0 を指定します。

autoArchiveInterval?:

number

= 7 days

自動アーカイブまでの時間（分）。最大期間（7日）にするには 0 を指定します。

autoDeleteInterval?:

number

= disabled

自動削除までの時間（分）。負の値にすると無効になり、0 にすると停止時に削除されます。

volumes?:

Array<{ volumeId: string; mountPath: string }>

Sandbox の作成時に接続する Daytona ボリューム。

networkBlockAll?:

boolean

= false

Sandbox からの外向きネットワークアクセスをすべて遮断するかどうか。

networkAllowList?:

string

ネットワークアクセスの制限時に許可する CIDR アドレスのカンマ区切りリスト。

domainAllowList?:

string

ネットワークアクセスの制限時に許可するドメインのカンマ区切りリスト。*.githubusercontent.com などのワイルドカードに対応します。IP アドレスが変わるサービスでは networkAllowList の代わりに使用してください。

プロパティ

id:

string

Sandbox インスタンスの識別子。

name:

string

Provider 名（'DaytonaSandbox'）。

provider:

string

Provider 識別子（'daytona'）。

status:

ProviderStatus

'pending' | 'initializing' | 'ready' | 'stopped' | 'destroyed' | 'error'

instance:

Sandbox

基盤となる Daytona Sandbox インスタンス。Sandbox が起動していない場合は SandboxNotReadyError をスローします。

processes:

DaytonaProcessManager

バックグラウンドプロセスマネージャー。SandboxProcessManager リファレンスを参照してください。

バックグラウンドプロセス

DaytonaSandbox には、バックグラウンドプロセスを起動・管理するプロセスマネージャーが組み込まれています。プロセスは、セッションベースのコマンド実行を使用して Daytona クラウド Sandbox 内で動作します。

const sandbox = new DaytonaSandbox({ language: 'typescript' })
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()

完全な API は、SandboxProcessManager リファレンスを参照してください。

クラウドストレージのマウント

Daytona Sandbox は S3 または GCS バケットをマウントし、クラウドストレージを Sandbox 内のローカルディレクトリとして利用できます。次の用途に便利です。

• クラウドバケットに保存された大規模データセットの処理
• クラウドストレージへの出力ファイルの直接書き込み
• Sandbox セッション間でのデータ共有

使用例は、Filesystem のマウントを参照してください。

Daytona Sandbox は FUSE（Filesystem in Userspace）を使用してクラウドストレージをマウントします。

• S3/R2：s3fs-fuse を介してマウント
• GCS：gcsfuse を介してマウント

必要な FUSE Tool が Sandbox イメージにない場合は、マウント時に自動的にインストールされます。

S3 の環境変数

変数	説明
S3_BUCKET	バケット名
S3_REGION	AWS リージョン、R2/MinIO の場合は auto
S3_ACCESS_KEY_ID	アクセスキー ID
S3_SECRET_ACCESS_KEY	シークレットアクセスキー
S3_ENDPOINT	エンドポイント URL（S3 互換の場合のみ）

GCS の環境変数

変数	説明
GCS_BUCKET	バケット名
GCS_SERVICE_ACCOUNT_KEY	サービスアカウントキーの JSON（パスではなく完全な JSON 文字列）

スナップショットでコールドスタートの遅延を短縮する

デフォルトでは、最初のマウント時に s3fs と gcsfuse が apt でインストールされるため、起動時間が長くなります。これを避けるには、Daytona スナップショットに事前導入し、snapshot オプションでスナップショット名を渡します。

方法1：宣言的なイメージビルド

import { Daytona, Image } from '@daytonaio/sdk'

const template = Image.base('daytonaio/sandbox')
  .runCommands('sudo apt-get update -qq')
  .runCommands('sudo apt-get install -y s3fs')
  // gcsfuse requires the Google Cloud apt repository
  .runCommands(
    'sudo mkdir -p /etc/apt/keyrings && ' +
      'curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && ' +
      'sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && ' +
      // Use gcsfuse-jammy for Ubuntu, gcsfuse-bookworm for Debian
      'echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-jammy main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list',
  )
  .runCommands('sudo apt-get update -qq && sudo apt-get install -y gcsfuse')

const daytona = new Daytona()

await daytona.snapshot.create(
  {
    name: 'cloud-fs-mounting',
    image: template,
  },
  { onLogs: console.log },
)

方法2：Dockerfile： Image.fromDockerfile() を使用します。

FROM daytonaio/sandbox
RUN sudo apt-get update -qq
RUN sudo apt-get install -y s3fs
# Use gcsfuse-jammy for Ubuntu, gcsfuse-bookworm for Debian
RUN sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-jammy main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list
RUN sudo apt-get update -qq && sudo apt-get install -y gcsfuse

import { Daytona, Image } from '@daytonaio/sdk'

const daytona = new Daytona()

await daytona.snapshot.create(
  {
    name: 'cloud-fs-mounting',
    image: Image.fromDockerfile('./Dockerfile'),
  },
  { onLogs: console.log },
)

次に、Sandbox 設定でスナップショット名を使用します。

const workspace = new Workspace({
  mounts: {
    '/s3-data': new S3Filesystem({/* ... */}),
    '/gcs-data': new GCSFilesystem({/* ... */}),
  },
  sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
})

SDK への直接アクセス

WorkspaceSandbox インターフェースに公開されていない Filesystem、git、その他の操作には、基盤となる Daytona Sandbox インスタンスへアクセスします。

const daytonaSandbox = sandbox.instance

// Upload a file
await daytonaSandbox.fs.uploadFile(Buffer.from('hello'), '/tmp/hello.txt')

// Run git operations
await daytonaSandbox.git.clone('https://github.com/org/repo', '/workspace/repo')

Sandbox がまだ起動していない場合、instance getter は SandboxNotReadyError をスローします。

Sandbox の作成モード

DaytonaSandbox は、指定されたオプションに基づいて作成モードを選択します。

オプション	作成モード
snapshot を設定	スナップショットベース（snapshot は image より優先）
image を設定（snapshot なし）	イメージベース（任意で resources を指定）
どちらも未設定	デフォルトのスナップショットベース

リソースは image が設定されている場合にのみ適用されます。image なしで resources を渡しても効果はありません。

関連項目

• SandboxProcessManager リファレンス
• WorkspaceSandbox インターフェース
• LocalSandbox リファレンス
• S3Filesystem リファレンス
• GCSFilesystem リファレンス
• Workspace の概要