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

# Box Mount

> BoxフォルダをPOSIXファイルシステムとしてエージェント実行環境にマウントします。双方向の同期が維持され、すべての操作にBoxの権限とガバナンスが適用されます。

Box Mountは、Boxコンテンツを標準的なPOSIXファイルシステムとして任意のエージェント実行環境で利用できるようにします。エージェントは、使い慣れたファイル操作を使用してファイルの読み取り、書き込み、および編集を行います。すべての操作には、Boxのセキュリティ、ガバナンス、およびアクセス制御が適用されます。継続的な双方向の同期により、エージェント側のコンテンツとBox上のコンテンツは同期された状態に保たれます。そのため、組み込みの競合防止機能が有効な状態で、ユーザーとエージェントは同じフォルダ内でコラボレーションできます。

<Note>
  Box Mountは現在、プライベートプレビュー段階です。一般公開はされておらず、本番環境向けのSLAの対象外です。また、正式リリースまでに機能が変更される可能性があります。Boxはプレビュー参加者にバイナリと設定ガイダンスを提供しています。アクセス権限をリクエストするには、[Box Mountプライベートプレビューの利用申請フォーム](https://bit.ly/box-mount-preview)に必要事項を入力してください。
</Note>

## Box Mountの仕組み

Box Mountは、バックグラウンドで同期プロセス (デーモン) を実行し、自社製品がプロビジョニングしたサンドボックス内のローカルディレクトリにBoxフォルダをマッピングします。Daytona、Docker、E2B、Vercel Sandboxなどのサポート対象Linuxサンドボックスで利用でき、特定ベンダーに依存しません。

* **コンテンツはBoxに保持されます。**エージェントはローカルパスを対象に操作を実行し、すべての操作はBox APIを介して実行されます。
* **ガバナンスはコンテンツに追従します。**すべての操作は、Box Mountが認証したIDとして実行されます。そのため、Box Shieldの分類ベースのセキュリティポリシーとともに、そのIDの権限、リテンション、リーガルホールド、情報バリア、監査証跡がエージェントに適用されます。OAuthモードでは、IDはアプリを承認したユーザーです。そのため、ユーザーがアクセスできないコンテンツにエージェントがアクセスすることはできません。JWTモードでは、IDはサービスアカウントです。そのため、そのアカウントのスコープをエージェントが必要とするコンテンツに設定します。
* **同期は双方向で実行されます。**エージェントがマウント上で行った変更はBoxにアップロードされ、ユーザーや他のエージェントによる更新はマウントに反映されます。
* **競合は上書きされずに保持されます。**ユーザーやエージェントが同じファイルを同時に変更した場合、Box Mountはアップロード時に競合を検出し、両方の結果を新しいBoxバージョンまたは別個の競合コピーとして保持します。そのため、レビュー担当者は変更内容をマージしたり、Boxのバージョン履歴を利用してロールバックしたりできます。

エージェントはコンテンツをプレーンファイルとして扱うため、ほとんどのツールではBoxコンテンツであることを意識せずに利用できます。ファイルを直接編集するのではなく、置き換えることで保存するアプリケーションは挙動が異なるため、最初に[既知の制限](#known-limitations)を確認してください。

## Box Mountの実際の動作を確認する

このデモでは、契約書レビューエージェントを構築します。このエージェントは、BoxフォルダをE2Bサンドボックス内にマウントし、そのワークスペース上でエージェントを実行し、完了したレビュー結果をBoxに同期して、ユーザーがレビューできるようにします。

<iframe width="100%" height="500" src="https://www.youtube.com/embed/bLyPe0FTc5w" title="Box MountとE2Bで契約書レビューエージェントを構築する" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

このデモで利用しているアーキテクチャやその他のワークフローパターンについては、Boxブログの[Meet Box Mount: A Box workspace for sandboxed AI agents](https://blog.box.com/meet-box-mount-box-workspace-sandboxed-ai-agents)を参照してください。

## 始める前に

以下が必要です。

* Box Mountのバイナリを含む、Box Mountプライベートプレビューへのアクセス権限。アクセス権限をリクエストするには、[Box Mountプライベートプレビューの利用申請フォーム](https://bit.ly/box-mount-preview)に必要事項を入力してください。
* [開発者コンソール](https://app.box.com/developers/console)のBoxアプリ。[OAuth 2.0](/guides/authentication/oauth2/oauth2-setup)または[JWT](/guides/authentication/jwt/jwt-setup)認証のいずれかに構成しておきます。
* マウントするBoxフォルダのID。これは、BoxのフォルダURLの末尾の数値です。

### サポート対象プラットフォーム

Box Mountは、x86\_64およびARM64アーキテクチャ上で動作するLinux実行環境をサポートしています。macOSはサポートしていません。

## コマンド

| コマンド | 実行する操作 |
| - | - |
| `box-mount config` | 資格情報および同期設定を対話形式で構成します |
| `box-mount mount "<local-dir>" "<box-id>"` | Boxフォルダを`<local-dir>` (絶対ローカルパス) にマウントします。`<box-id>`はBoxフォルダIDです |
| `box-mount status` | 現在のマウントの状態を報告します |
| `box-mount unmount "<local-dir>"` | 絶対パスを使用してローカルディレクトリをマウント解除します |
| `box-mount unmount --reset-force "<local-dir>"` | すべてのローカルマウントをマウント解除し、そのコンテンツを強制的に削除します |

最初のセッションは次のようになります。

```bash theme={null}
box-mount config
mkdir -p /mnt/box
box-mount mount "/mnt/box" "123456789"
box-mount status
```

これで、エージェントは`/mnt/box`を対象に動作するようになります。

## 資格情報の構成

Box Mountは、`--data-path`に渡したパスまたは`~/.box-mount/`にある`box-config.json`ファイルからBox資格情報を読み取ります。

`config`コマンドは、対話形式による構成を1ステップで処理し、`~/.box-mount/box-config.json`に書き込みます。

```bash theme={null}
box-mount config
```

Box Mountは、OAuthとJWTの2つの認証モードをサポートしています。デフォルトはOAuthです。求められたら、`oauth`または`jwt`を入力します。[資格情報の保護](#secure-your-credentials)で説明されているとおり、構成ファイルおよびその構成ファイルが参照するJWTの秘密キーJSONを制限します。

### OAuthの手動構成

`~/.box-mount/box-config.json`を作成し、Boxアプリの資格情報を入力します。

```json theme={null}
{
  "client_id":     "YOUR_BOX_CLIENT_ID",
  "client_secret": "YOUR_BOX_CLIENT_SECRET",
  "access_token":  "",
  "refresh_token": "",
  "redirect_uri":  "http://localhost:3000/callback"
}
```

| フィールド | 必須 | メモ |
| - | - | - |
| `client_id` | はい | 開発者コンソールから |
| `client_secret` | はい | 開発者コンソールから |
| `access_token` | はい | `box-mount config`を実行してOAuthを通じて取得します |
| `refresh_token` | OAuthのみ | `box-mount config`を実行してOAuthを通じて取得します。更新のたびにローテーションされます |
| `redirect_uri` | いいえ | Boxアプリの設定と完全に一致している必要があります。OAuthを構成する場合に使用します |

OAuth構成には、OAuthがデフォルトのモードであるため、`auth_type`フィールドはありません。`auth_type`はJWTに切り替える場合にのみ設定します。

### JWTの手動構成

JWTサービスアカウントを使用する場合、構成に必要なのは以下の2つのフィールドだけです。

```json theme={null}
{
  "auth_type": "jwt",
  "jwt_config_path": "/path/to/box-jwt-config.json"
}
```

| フィールド | 必須 | メモ |
| - | - | - |
| `auth_type` | はい | 必ず`jwt`と指定 |
| `jwt_config_path` | はい | 開発者コンソールのJWT JSONの絶対パス |

`jwt_config_path`には、開発者コンソールによって生成されたJSONファイルのパスを指定する必要があります。このJSONファイルを作成するには、アプリの \[**構成**] タブを開き、\[**アプリの設定**] セクションで \[**公開/秘密キーペアを生成**] を選択します。JWT認証では、SDKが自動的に有効期間の短いアクセストークンを取得するため、`access_token`および`refresh_token`は不要です。

### 環境変数の使用

資格情報の各フィールドは、JSONファイルの代わりに環境変数で指定できます。環境変数は、JSONファイルの値より優先されます。また、この方法ですべての必須フィールドを指定する場合、JSONファイルは省略可能です。

| 変数 | 構成キー | メモ |
| - | - | - |
| `BOX_CLIENT_ID` | `client_id` | OAuthアプリのクライアントID |
| `BOX_CLIENT_SECRET` | `client_secret` | OAuthアプリのクライアントシークレット |
| `BOX_ACCESS_TOKEN` | `access_token` | 現在のアクセストークン。プロセス中に更新され、更新時に構成ファイルに自動的に書き戻されます |
| `BOX_REFRESH_TOKEN` | `refresh_token` | 現在の更新トークン。書き戻し動作はアクセストークンと同じです |
| `BOX_AUTH_TYPE` | `auth_type` | JWTモードを有効にする場合は、`jwt`に設定します |
| `BOX_JWT_CONFIG_PATH` | `jwt_config_path` | 開発者コンソールのJWT JSONのパス。JWTモードのみ |

<Warning>
  `BOX_ACCESS_TOKEN`や`BOX_REFRESH_TOKEN`を、`.zprofile`や`.bashrc`などのシェル起動ファイルに保存しないでください。Box Mountはトークンを更新すると、新しい値を`~/.box-mount/box-config.json`に書き込みます。そのため、環境変数に埋め込まれたトークンのコピーは古くなり、古いトークンは次回実行時に認証エラーの原因となります。これらの環境変数は、セッションの期間中のみエクスポートするようにしてください。

  また、`BOX_*`資格情報をLLMエージェントやその他の信頼できないプロセスの実行環境に配置しないでください。[資格情報の保護](#secure-your-credentials)を参照してください。
</Warning>

### 開発者トークンの使用

[開発者トークン](/guides/authentication/tokens/developer-tokens)は、開発者コンソールで生成する有効期間の短いトークンです。60分間有効で、更新できません。OAuthフロー全体を実装せずにすばやくテストする場合に便利です。

`~/.box-mount/box-config.json`に`access_token`を設定し、`refresh_token`は空のままにします。

```json theme={null}
{
  "client_id":     "YOUR_BOX_CLIENT_ID",
  "client_secret": "YOUR_BOX_CLIENT_SECRET",
  "access_token":  "PASTE_DEVELOPER_TOKEN_HERE",
  "refresh_token": ""
}
```

トークンは環境変数で渡すこともできます。その場合は構成ファイルは不要です。

```bash theme={null}
export BOX_ACCESS_TOKEN="PASTE_DEVELOPER_TOKEN_HERE"
box-mount mount "/local/path" "123456789"
```

開発者トークンは更新できないため、トークンが期限切れになるとBox Mountは同期を停止します。再開するには、開発者コンソールで新しいトークンを生成して`access_token`を更新するか、環境変数を再エクスポートしてください。

## トークンのライフサイクル

OAuthモードの場合:

* アクセストークンは約60分後に期限切れになり、SDKによって自動的に更新されます。
* 更新のたびに更新トークンがローテーションされ、古い更新トークンは即座に無効になります。
* ローテーションされたトークンは`~/.box-mount/box-config.json`に書き戻されます。
* 更新トークンは60日間使用されないと期限切れとなります。`box-mount config`をもう一度実行すると、OAuthフローが繰り返されます。

JWTモードの場合:

* SDKはJWTアサーションに署名し、それを有効期間の短いアクセストークンと交換して、そのトークンを自動的に更新します。トークンはメモリにのみ保持されるため、`box-config.json`には何も書き込まれません。
* JWTの構成JSONと秘密キーが有効であれば、認証にユーザーの操作は必要ありません。

## 資格情報の保護

Box資格情報はBox APIのIDであり、そのIDの権限スコープは通常、マウントしたフォルダよりも広くなります。これは、`box-config.json`のOAuthクライアントのシークレットとトークン、`BOX_*`環境変数、およびディスク上のJWTの秘密キーJSONに当てはまります。それらを読み取る権限があれば、マウント内のファイルを読み取るだけでなく、そのアプリやユーザーとしてBox APIを呼び出すことができます。

`box-mount mount`が起動するデーモンはそれらの資格情報を必要としますが、他のプロセスと共有する必要があるのはマウントディレクトリのみです。構成、データベース、プロセスID、ログを保持する`~/.box-mount/`には、Box Mountを実行するアカウント以外がアクセスできないようにします。

### エージェントサンドボックスでの推奨設定

LLMエージェントをBox Mountと同じマシン上で実行する場合、デーモンと同じUnixユーザーとしてエージェントを実行しないでください。以下の2つのユーザーを使用します。

| ロール | Unixユーザー | アクセス可能な対象 |
| - | - | - |
| Box Mountデーモン | ユーザーA | `~/.box-mount/`、JWT JSON、およびマウントディレクトリ |
| LLMエージェント | ユーザーB | マウントディレクトリのみ |

1. 2つのユーザーを作成します。ユーザーAとして`box-mount config`を実行し、`~/.box-mount/`がユーザーAのホームディレクトリ内に作成されるようにします。まだマウントしないでください。ブートストラップ処理によってツリー構造が生成され、先に共有権限を空のマウントディレクトリに設定する必要があるからです。

2. 資格情報に対するアクセスを、ユーザーAのみが読み取ることができるように制限します。その後、`ls -l`を使用して所有権を確認します。モード`644` (全ユーザーが読み取り可能) は、これらのファイルには適切ではありません。

   ```bash theme={null}
   chmod 700 ~/.box-mount
   chmod 600 ~/.box-mount/box-config.json
   chmod 600 /path/to/box-jwt-config.json   # JWT mode only
   ```

3. 共有グループ、setgid、およびデフォルトのPOSIX ACLを使用して、マウントディレクトリのみをユーザーBと共有します。setgidは、グループ所有権を新しいinodeにコピーします。また、デフォルトのACLはグループの書き込みアクセス権限を継承します。この設定を空のディレクトリに適用してから、マウントします。`setfacl`コマンドは`acl`パッケージに含まれています。

   ```bash theme={null}
   sudo mkdir -p /path/to/mount
   sudo groupadd boxmount
   sudo usermod -aG boxmount userA
   sudo usermod -aG boxmount userB
   sudo chown userA:boxmount /path/to/mount
   sudo chmod 2770 /path/to/mount
   sudo setfacl -m g:boxmount:rwx -m d:g:boxmount:rwx /path/to/mount
   box-mount mount "/path/to/mount" "<box-id>"   # as user A
   ```

   ユーザーBには、ユーザーAのホームディレクトリ、`--data-path`、およびJWTファイルに対する読み取りアクセス権限を持たせないようにする必要があります。また、ユーザーBはマウントより上位にあるすべてのディレクトリをトラバースできる必要があるため、この例ではマウントをホームディレクトリの外に配置しています。マウントを代わりにユーザーAのホームディレクトリ内に配置しても、ホームディレクトリが`750`に設定されていると、マウントディレクトリ自体が`2770`であっても、ユーザーBはブロックされます。

4. ユーザーBとしてエージェントを起動します。エージェントのシェル、systemdユニット、またはコンテナ仕様には、`BOX_CLIENT_ID`、`BOX_CLIENT_SECRET`、`BOX_ACCESS_TOKEN`、`BOX_REFRESH_TOKEN`、`BOX_JWT_CONFIG_PATH`をエクスポートしないでください。エクスポートすると、これらの値がプロセス環境から参照可能になります。これらの値は、ユーザーAのデーモンプロセスのみが保持するようにします。

5. JWTモードでは、企業の管理者のキーペアではなく、エージェントが必要とするコンテンツにスコープが設定されたサービスアカウントを使用します。

個人用マシンで、マウントを使用するプロセスが自分だけである場合は、自分のユーザーアカウントでBox Mountを実行するのが一般的であり、`$HOME`にSSHキーを保存するのと同じモデルに従います。もう一方のプロセスが信頼できないエージェントである場合、この構成は適切ではありません。

<Warning>
  この分離は、マシン上のルート、カーネルの悪用、またはエージェントをユーザーAとして実行するケースに対する保護を提供するものではありません。また、マウント内でエージェントが実行できる操作を制限するものでもありません。ユーザーBはそのツリーに対して通常のファイルシステムアクセス権限を持っているためです。
</Warning>

## データおよびログの場所

デフォルトでは、`--data-path`は`~/.box-mount/`を指しており、Box Mountはそれを基準にして他のすべてのパスを導出します。

| パス | 内容 |
| - | - |
| `~/.box-mount/mount.json` | マウントレコード |
| `~/.box-mount/box-config.json` | Box資格情報 |
| `~/.box-mount/local-config.json` | ローカル同期設定 |
| `~/.box-mount/data/` | `sync.sqlite3`、`bdlc.pid`、`teardown.json`。teardown.jsonは、リセットまたはマウント解除が完了していないときにのみ存在します。 |
| `~/.box-mount/logs/` | デーモン出力の`box-mount-sync.stdout.log`および`box-mount-sync.stderr.log`、さらに各実行の`box-mount-sync-YYYYMMDD-HHMMSS-ffffff.log`ファイル |

このツリーは、デーモン専用として扱ってください。[資格情報の保護](#secure-your-credentials)を参照してください。

## 既知の制限

### アトミックセーブの非サポート

Box Mountは、アトミックセーブ (セーフライトとも呼ばれます) をサポートしていません。アトミックセーブとは、アプリケーションが、ファイルを直接編集する代わりに、一時ファイルに書き込んだ後、その一時ファイルの名前を変更して元のファイルを置き換えるファイルの保存方法です。この方法で保存されたファイルは、Boxのバージョン履歴が失われます。これは、Box Mountが置き換え後のファイルを、既存ファイルの新しいバージョンとしてではなく、新しいファイルとして同期するためです。

### ワークロードの制限

プレビュー段階では、1マウントあたり最大5 GBのコンテンツおよび10,000ファイルまでの、本番環境以外のワークロードに利用してください。

## 関連ツール

Box Mountは、エージェントがBoxコンテンツにアクセスするための他の方法を補完するものです。エージェントがファイルを直接操作する必要がある場合はBox Mountを使用し、APIレベルまたはコマンドラインでアクセスする場合は以下のツールを使用します。

| ツール | 用途 |
| - | - |
| [Box MCPサーバー](/guides/box-mcp) | エージェントに、Box検索、Box AI、およびファイル操作に対するツールベースのアクセス権限を提供する |
| [Box CLI](/guides/cli) | コマンドラインからBoxのルーチン操作や一括操作を実行する |
| [Box SDK](/guides/tooling/sdks) | Box APIを直接利用するアプリケーションを開発する |
