> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# DaytonaSandbox

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

## インストール

**npm**:

```bash
npm install @mastra/daytona
```

**pnpm**:

```bash
pnpm add @mastra/daytona
```

**Yarn**:

```bash
yarn add @mastra/daytona
```

**Bun**:

```bash
bun add @mastra/daytona
```

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

**シェルでエクスポート**:

```bash
export DAYTONA_API_KEY=your-api-key
```

**.env ファイル**:

```bash
DAYTONA_API_KEY=your-api-key
```

**コンストラクター**:

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

## 使用方法

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

```typescript
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!
```

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

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

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

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

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

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

### 一時的な Sandbox

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

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

### 出力のストリーミング

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

```typescript
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 が再開されます。

```typescript
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 が自動的にマウントされます。

```typescript
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

```typescript
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）

```typescript
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

```typescript
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',
)
```

### ネットワーク分離

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

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

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

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

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

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

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

**id** (`string`): この Sandbox インスタンスの一意な識別子。 (Default: `Auto-generated`)

**apiKey** (`string`): 認証用の Daytona API キー。未指定の場合は環境変数 DAYTONA\_API\_KEY を使用します。

**apiUrl** (`string`): Daytona API エンドポイント。未指定の場合は環境変数 DAYTONA\_API\_URL を使用します。

**target** (`string`): Runner リージョン。未指定の場合は環境変数 DAYTONA\_TARGET を使用します。

**timeout** (`number`): デフォルトの実行タイムアウト（ミリ秒）。 (Default: `300000 (5 minutes)`)

**language** (`'typescript' | 'javascript' | 'python'`): Sandbox のランタイム言語。 (Default: `'typescript'`)

**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 に設定する環境変数。 (Default: `{}`)

**labels** (`Record<string, string>`): カスタムメタデータラベル。 (Default: `{}`)

**name** (`string`): Sandbox の表示名。 (Default: `Sandbox id`)

**user** (`string`): コマンドを実行する OS ユーザー。 (Default: `'daytona'`)

**public** (`boolean`): ポートプレビューを公開するかどうか。 (Default: `false`)

**ephemeral** (`boolean`): 停止時に Sandbox を直ちに削除するかどうか。 (Default: `false`)

**autoStopInterval** (`number`): 自動停止までの時間（分）。無効にするには 0 を指定します。 (Default: `15`)

**autoArchiveInterval** (`number`): 自動アーカイブまでの時間（分）。最大期間（7日）にするには 0 を指定します。 (Default: `7 days`)

**autoDeleteInterval** (`number`): 自動削除までの時間（分）。負の値にすると無効になり、0 にすると停止時に削除されます。 (Default: `disabled`)

**volumes** (`Array<{ volumeId: string; mountPath: string }>`): Sandbox の作成時に接続する Daytona ボリューム。

**networkBlockAll** (`boolean`): Sandbox からの外向きネットワークアクセスをすべて遮断するかどうか。 (Default: `false`)

**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 内で動作します。

```typescript
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` リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)を参照してください。

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

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

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

使用例は、[Filesystem のマウント](#filesystem-mounting)を参照してください。

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

- **S3/R2**：[s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) を介してマウント
- **GCS**：[gcsfuse](https://github.com/GoogleCloudPlatform/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：宣言的なイメージビルド**

```typescript
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()`](https://www.daytona.io/docs/typescript-sdk/image#fromdockerfile) を使用します。

```dockerfile
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
```

```typescript
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 設定でスナップショット名を使用します。

```typescript
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` インスタンスへアクセスします。

```typescript
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 リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [LocalSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox)
- [S3Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)
- [GCSFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)