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

# CLI を使用してサンドボックスを管理する

> Sandboxes CLI をインストールして、サンドボックスの確認、コマンドの実行、ファイルの転送、スナップショットの管理を行います。

`cwsandbox` コマンドラインインターフェース (CLI) を使用すると、既存の CoreWeave サンドボックスをターミナルから管理できます。サンドボックスの確認、コマンドの実行、ログの取得、ファイルの転送、ファイルシステムスナップショットの管理、リソースのクリーンアップなどを行えます。CLI は、[Sandboxes Python クライアント](https://docs.coreweave.com/ja/products/sandboxes/client.md)のオプションの追加機能としてインストールします。

CLI を使用する前に、SDK でサンドボックスを作成しておく必要があります。作成方法については、[サーバーレスのクイックスタート](https://docs.coreweave.com/ja/products/sandboxes/get-started.md)または[独自のコンピューティングリソースを使用する](https://docs.coreweave.com/ja/products/sandboxes/get-started-cks.md)を参照してください。

## 前提条件

開始する前に、次のものを準備してください。

* `uv` がインストールされ、有効化された [Python 3.11 以降の仮想環境](https://docs.coreweave.com/ja/products/sandboxes/client.md#prepare-your-python-environment)。
* サンドボックスを所有するアカウントの認証情報。認証情報のセットアップと必要なロールについては、[認証情報の選択と取得](https://docs.coreweave.com/ja/products/sandboxes/placement.md#choose-and-get-credentials)を参照してください。
* 実行中のサンドボックス。コマンドの実行、インタラクティブシェル、ログの取得、ファイル操作、スナップショットの作成に使用します。

## インストールと認証

サンドボックスの作成に使用した認証情報を選択してください。有効化した仮想環境で、いずれかのタブのコマンドを実行します。その際、認証情報のプレースホルダーをご自身のキーまたはトークンに置き換えてください。

**Forge API キー**

`cli` と `wandb` の extras をインストールし、Forge API キーを使用するために W\&B の認証方式を選択します。

```bash theme={"system"}
uv pip install --upgrade 'cwsandbox[cli,wandb]'
export WANDB_API_KEY="WANDB_API_KEY_VALUE"
export CWSANDBOX_AUTH="wandb"
cwsandbox --help
```

**CoreWeave API アクセストークン**

`cli` の extra をインストールし、CoreWeave 認証を選択します。

```bash theme={"system"}
uv pip install --upgrade 'cwsandbox[cli]'
export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
export CWSANDBOX_AUTH="coreweave_api_key"
cwsandbox --help
```

ヘルプの出力に、利用可能なコマンドの一覧が表示されます。以降の例を実行するターミナルでは、認証用の変数を設定したままにしておいてください。

`CWSANDBOX_AUTH` で認証方式を選択します。top-level の `--auth` オプションを指定すると、1 回の invocation に限りこの設定を上書きできます。たとえば、Forge の依存関係と認証情報を設定済みの場合は次のようになります。

```bash theme={"system"}
cwsandbox --auth wandb ls
```

各コマンドやサブコマンドのオプションを確認するには、`--help` を使用します。

```bash theme={"system"}
cwsandbox exec --help
cwsandbox files read --help
cwsandbox snapshots create --help
```

## サンドボックスを検索する

お使いの認証情報で参照できるサンドボックスを一覧表示します：

```bash theme={"system"}
cwsandbox ls
```

ステータスでフィルターするか、ステータスとタグを組み合わせてフィルターします。`TAG` は、サンドボックスに付加したタグに置き換えてください。

```bash theme={"system"}
cwsandbox ls --status running
cwsandbox ls --status running --tag "TAG" --output json
```

デフォルトの表には、サンドボックス ID、ステータス、ランナー、開始時刻が表示されます。`--output json` を指定すると、構造化された出力が返されます。複数のフィルター値を指定するには、`--tag` または `--runner-id` を繰り返し指定します。

## サンドボックスを確認する

`SANDBOX_ID_VALUE` を `cwsandbox ls` で取得した ID に置き換えて、ターミナルで設定します。

```bash theme={"system"}
export SANDBOX_ID="SANDBOX_ID_VALUE"
cwsandbox get "$SANDBOX_ID"
cwsandbox get "$SANDBOX_ID" --output json
```

以下の例では、この変数を使用します。詳細情報には、サンドボックスのステータス、ランナー情報、開始時刻のほか、利用可能な場合は終了コードが含まれます。

## コマンドの実行

実行中のサンドボックスでコマンドを実行します。実行するコマンドは、サンドボックスのイメージで利用可能である必要があります。

```bash theme={"system"}
cwsandbox exec "$SANDBOX_ID" echo hello
cwsandbox exec "$SANDBOX_ID" python -c "print('hello')"
```

リモートの作業ディレクトリを設定するには、リモートコマンドの前に `--cwd` を指定します。`REMOTE_DIRECTORY` は、サンドボックス内の既存のディレクトリに置き換えてください。

```bash theme={"system"}
cwsandbox exec "$SANDBOX_ID" --cwd "REMOTE_DIRECTORY" pwd
```

CLI は標準出力と標準エラー出力をローカルのターミナルにストリーミングします。リモートコマンドが正常に完了すると、CLI はそのコマンドと同じ終了コードで終了します。

## インタラクティブシェルを開く

macOS または Linux のローカルターミナルから、次のコマンドでインタラクティブシェルを開きます。

```bash theme={"system"}
cwsandbox sh "$SANDBOX_ID"
```

デフォルトのシェルは `/bin/bash` です。別のシェルや、サンドボックスにインストールされている対話型プログラムを選択するには、`--cmd` を使用します：

```bash theme={"system"}
cwsandbox sh "$SANDBOX_ID" --cmd /bin/sh
cwsandbox sh "$SANDBOX_ID" --cmd "python -i"
```

インタラクティブシェルを使用するには、標準入力と標準出力の両方がターミナルに接続されている必要があります。なお、Windows ではサポートされていません。シェルセッションを終了するには、`exit` と入力するか `Ctrl+D` を押します。`Ctrl+C` はリモートのプロセスに転送されます。

## ログを表示する

サンドボックスのメインプロセスのログを取得します。

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --tail 100
cwsandbox logs "$SANDBOX_ID" --tail 100 --timestamps
```

新しいログ出力をストリームで表示するには、`--follow` を使用します。追跡を停止するには `Ctrl+C` を押します。

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --follow
```

タイムスタンプでログをフィルターするには、`--since` を使用します。`2026-09-10 09:00:00` は、任意の開始時刻に置き換えてください。タイムゾーンを指定しないタイムスタンプは、CLI では UTC として解釈されます。

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --since "2026-09-10 09:00:00"
```

ログには、メインプロセス (サンドボックスの作成に使用したコマンド) の標準出力と標準エラー出力が含まれます。`cwsandbox exec` の出力は含まれません。デフォルトのキープアライブコマンドで作成したサンドボックスでは、ログは出力されません。

ログを取得するには、サンドボックスが実行中である必要があります。ログはサンドボックスを停止する前に取得してください。詳細については、次を参照してください: [サンドボックスのログ](https://docs.coreweave.com/ja/products/sandboxes/client/guides/logging.md)。

## ファイルの読み取りと書き込み

ファイル操作を行うには、サンドボックスが実行中である必要があります。リモートファイルの内容を標準出力に表示するには、`REMOTE_PATH` をサンドボックス内のファイルパスに置き換えます。

```bash theme={"system"}
cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH"
```

ファイルをダウンロードするには、`--output` オプションを追加してローカルの保存先を指定します。`LOCAL_PATH` は、ファイルを保存するパスに置き換えてください。

```bash theme={"system"}
cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH" --output "LOCAL_PATH"
```

ファイルをアップロードするには、先にリモートのアップロード先を、次に既存のローカルのソースファイルを指定します。

```bash theme={"system"}
cwsandbox files write "$SANDBOX_ID" "REMOTE_PATH" "LOCAL_PATH"
```

## ファイルシステムスナップショットを管理する

スナップショットを作成するには、[ファイルシステムスナップショットマウント](https://docs.coreweave.com/ja/products/sandboxes/file-system-snapshots.md#start-a-sandbox-with-a-snapshot-mount)が設定済みで、実行中のサンドボックスが必要です。また、組織でファイルシステムスナップショットが有効になっている必要があります。

スナップショットを作成するには、次のようにします。

```bash theme={"system"}
cwsandbox snapshots create "$SANDBOX_ID"
```

このコマンドは、スナップショットが準備完了になるまで待機してから、その ID を出力します。準備完了を待たずにすぐに制御を返し、ID を JSON 形式で出力するには、次のコマンドを使用します。

```bash theme={"system"}
cwsandbox snapshots create "$SANDBOX_ID" --no-wait --output json
```

スナップショットを一覧表示するか、特定のサンドボックスから作成された準備完了状態のスナップショットのみに絞り込みます。

```bash theme={"system"}
cwsandbox snapshots list
cwsandbox snapshots list --source-sandbox-id "$SANDBOX_ID" --status ready
```

スナップショットの詳細を確認するには、`SNAPSHOT_ID_VALUE` を対象のスナップショット ID に置き換えます。

```bash theme={"system"}
export SNAPSHOT_ID="SNAPSHOT_ID_VALUE"
cwsandbox snapshots get "$SNAPSHOT_ID"
cwsandbox snapshots get "$SNAPSHOT_ID" --output json
```

不要になったスナップショットを削除するには、次のコマンドを実行します。

```bash theme={"system"}
cwsandbox snapshots delete "$SNAPSHOT_ID"
```

スナップショットの要件、サポートされるストレージ、SDK を使用したサンドボックスのリストアについては、[ファイルシステムスナップショット](https://docs.coreweave.com/ja/products/sandboxes/file-system-snapshots.md)を参照してください。

## サンドボックスを停止または削除する

サンドボックスを使い終えたら、次のように停止します:

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID"
```

正常なシャットダウンのために最大 30 秒の猶予を設けるには、代わりに次の方法を使用します。

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID" --graceful-shutdown-seconds 30
```

ファイルシステムスナップショットのマウントを設定済みのサンドボックスでは、次の代替手段を使用して、停止前にスナップショットを取得します。

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID" --snapshot-on-stop
```

サンドボックスを削除するには、次のコマンドを実行します。

```bash theme={"system"}
cwsandbox delete "$SANDBOX_ID"
```

クリーンアップスクリプトでは、`--missing-ok` を使用して、すでに存在しないサンドボックスがあってもエラーにならないようにします:

```bash theme={"system"}
cwsandbox delete "$SANDBOX_ID" --missing-ok
```