> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックスにオブジェクトストレージバケットをマウントする

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/docs/ja/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

各サンドボックスインスタンスには、一時的なデータ操作用として、デフォルトで 20GB のエフェメラルなシステムディスクストレージがプロビジョニングされます。<u>サンドボックスが終了またはタイムアウトすると、このストレージ領域内のすべてのデータは自動的に消去されます</u>。したがって、長期保持が必要な永続データは、外部のクラウドストレージサービスに保存する必要があります。

<Tip>
  サンドボックスのストレージ割り当て仕様は変更される場合があります。現在のリソース割り当てと関連コストについては、[Pricing](/docs/ja/guides/sandbox-pricing) ドキュメントを参照してください。
</Tip>

オブジェクトストレージは、主要なクラウドサービスプロバイダーが提供する、高いスケーラビリティ、耐久性、コスト効率を備えたクラウドストレージアーキテクチャです。サンドボックス環境内では、オブジェクトストレージには主に 2 つの方法でアクセスできます。クラウドプロバイダーの SDK や CLI ユーティリティを使用して直接プログラムから操作する方法、または FUSE (Filesystem in Userspace) 実装を使用して、オブジェクトストレージバケットを標準的な POSIX 準拠のファイルシステムマウントとして提示する方法です。

<Tip>
  [FUSE (Filesystem in Userspace)](https://www.kernel.org/doc/html/next/filesystems/fuse.html) は、ユーザー空間アプリケーションで完全に機能するファイルシステムを実装できるようにするカーネルモジュールおよびユーザー空間ライブラリです。このフレームワークは、リモートクラウドストレージサービスを標準的なファイルシステム階層として提示する抽象化レイヤーを提供し、従来の POSIX インターフェースを通じた透過的なファイル操作を可能にします。
</Tip>

このドキュメントでは、主要なクラウドサービスプロバイダーのオブジェクトストレージバケットを、ファイルシステムマウント技術を通じてサンドボックス環境に統合するための包括的なガイダンスを提供します。

<Warning>
  FUSE ベースのオブジェクトストレージマウントは、ネットワークレイテンシとプロトコル変換レイヤーにより、I/O のパフォーマンスに大きなオーバーヘッドをもたらします。厳格なパフォーマンス要件を持つアプリケーションでは、このアプローチを避けるべきです。さらに、FUSE ファイルシステム操作にはネイティブのオブジェクトストレージ API に固有のアトミック性保証がないため、ローカルファイルシステム操作は成功した一方で対応するリモート操作が失敗し、データ不整合につながる可能性のある競合状態が発生し得ます。

  このマウント方式は、書き込み操作が少なく、パフォーマンス制約が緩い読み取り中心のワークロードに最適です。パフォーマンスが重要なアプリケーションや頻繁な書き込みパターンでは、クラウドプロバイダー SDK またはネイティブ REST API を使用した直接統合を強く推奨します。
</Warning>

<SandboxConfigHint />

## Amazon S3

Amazon S3 バケットは、標準的なファイル操作を通じて S3 バケットへのアクセスを提供する FUSE ベースのファイルシステム実装である [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) を使用して、POSIX 準拠のファイルシステムとしてマウントできます。

s3fs-fuse パッケージは、`novita.Dockerfile` にインストールコマンドを組み込むことで [sandbox template](/docs/ja/guides/sandbox-template-quickstart) の作成時に統合できます。または、アドホックな要件に対応するために、稼働中のサンドボックスインスタンス内で動的にインストールすることもできます。

次の `novita.Dockerfile` は、テンプレートビルド時に s3fs-fuse を統合する方法を示しています。

<CodeGroup>
  ```dockerfile novita.Dockerfile icon="docker" theme={"system"}
  # Compatible with Debian-based distributions
  FROM ubuntu:latest

  # Critical: s3fs versions below 1.93 contain known mounting issues. Ensure version compatibility.
  RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y s3fs
  ```
</CodeGroup>

次の実装は、s3fs-fuse を使用してサンドボックス環境内で S3 バケットをプログラムからマウントする方法を示しています。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox'

  const TEMPLATE_ID = process.env.NOVITA_TEMPLATE_ID
  const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
  const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
  const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME
  const AWS_REGION = process.env.AWS_REGION
  if (!TEMPLATE_ID || !AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_BUCKET_NAME || !AWS_REGION) {
      throw new Error('Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')
  }

  const MOUNT_DIRECTORY = "/mnt/s3-bucket"

  const sandbox = await Sandbox.create(TEMPLATE_ID)

  // Initialize mount point directory structure
  await sandbox.files.makeDir(MOUNT_DIRECTORY)

  // Configure s3fs credentials using standard credential file location
  // s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  await sandbox.files.write('/root/.passwd-s3fs', `${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}`)

  // Enforce secure credential file permissions (owner read-only)
  await sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

  // Execute S3 bucket mount operation with optimized parameters
  // Configuration parameters:
  // - allow_other: Enable cross-user filesystem access
  // - endpoint: Specify the AWS region endpoint for your bucket
  // Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  const mountOptions = `allow_other,endpoint=${AWS_REGION}`
  await sandbox.commands.run(`sudo s3fs ${AWS_BUCKET_NAME} ${MOUNT_DIRECTORY} -o ${mountOptions}`)

  // Validate mount functionality with write operation
  await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

  // Verify mount integrity through read operation
  const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
  console.log(content)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  import os
  from novita_sandbox.core import Sandbox

  TEMPLATE_ID = os.environ.get("NOVITA_TEMPLATE_ID")
  AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
  AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
  AWS_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")
  AWS_REGION = os.environ.get("AWS_REGION")
  if not TEMPLATE_ID or not AWS_ACCESS_KEY_ID or not AWS_SECRET_ACCESS_KEY or not AWS_BUCKET_NAME or not AWS_REGION:
      raise ValueError("Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION")

  MOUNT_DIRECTORY = "/mnt/s3-bucket"

  sandbox = Sandbox.create(TEMPLATE_ID)

  # Initialize mount point directory structure
  sandbox.files.make_dir(MOUNT_DIRECTORY)

  # Configure s3fs credentials using standard credential file location
  # s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  # Custom credential paths require explicit specification via -o passwd_file parameter
  sandbox.files.write("/root/.passwd-s3fs", f"{AWS_ACCESS_KEY_ID}:{AWS_SECRET_ACCESS_KEY}")

  # Enforce secure credential file permissions (owner read-only)
  sandbox.commands.run("sudo chmod 600 /root/.passwd-s3fs")

  # Execute S3 bucket mount operation with optimized parameters
  # Configuration parameters:
  # - allow_other: Enable cross-user filesystem access
  # - endpoint: Specify the AWS region endpoint for your bucket
  # Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  mount_options = f"allow_other,endpoint={AWS_REGION}"
  sandbox.commands.run(f"sudo s3fs {AWS_BUCKET_NAME} {MOUNT_DIRECTORY} -o {mount_options}")

  # Validate mount functionality with write operation
  write_result = sandbox.files.write(f"{MOUNT_DIRECTORY}/test-file.txt", "test-file-content")

  # Verify mount integrity through read operation
  content = sandbox.files.read(f"{MOUNT_DIRECTORY}/test-file.txt")
  print("File content:", content)

  sandbox.kill()
  ```
</CodeGroup>