> ## 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. # Sandbox > CWSandbox client with sync/async hybrid API. ソース: [src/cwsandbox/\_sandbox.py:1688](https://github.com/coreweave/cwsandbox-client/blob/v1.14.2/src/cwsandbox/_sandbox.py#L1688) ```python theme={"system"} class Sandbox(*, command: str | None = None, args: list[str] | None = None, defaults: SandboxDefaults | None = None, auth: AuthConfig | None = None, container_image: str | None = None, tags: list[str] | None = None, base_url: str | None = None, request_timeout_seconds: float | None = None, poll_retry_budget_seconds: float | None = None, poll_rpc_timeout_seconds: float | None = None, max_lifetime_seconds: float | None = None, profile_ids: list[str] | None = None, profile_names: list[str] | None = None, runner_ids: list[str] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, mounted_files: list[dict[str, Any]] | None = None, s3_mount: dict[str, Any] | None = None, ports: list[dict[str, Any]] | None = None, network: NetworkOptions | dict[str, Any] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, max_timeout_seconds: int | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, services: list[Service] | tuple[Service, ...] | None = None, volumes: list[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | tuple[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any], ...] | None = None, template_id: str | None = None, image_pull_credentials: ImagePullCredentials | dict[str, Any] | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, environment_variables: dict[str, str] | None = None, annotations: dict[str, str] | None = None, secrets: Sequence[Secret | dict[str, Any]] | None = None, data_plane_mode: DataPlaneMode | str | None = None, containers: Sequence[Container | Mapping[str, Any]] | None = None) ``` CWSandbox client with sync/async hybrid API. すべてのメソッドは即座に返り、sync と async の両方のコンテキストで使用できます。 操作は \_LoopManager によって管理されるバックグラウンドのイベントループで実行されます。

プロパティ

sandbox\_id

```python theme={"system"} @property def sandbox_id(self) -> str | None ``` まだ開始されていない場合は None、それ以外の場合は一意のサンドボックス ID。

returncode

```python theme={"system"} @property def returncode(self) -> int | None ``` サンドボックスが完了した場合の終了コード。まだ実行中の場合は None。

runner\_id

```python theme={"system"} @property def runner_id(self) -> str | None ``` サンドボックスが実行されているランナー。開始されていない場合は None。

status

```python theme={"system"} @property def status(self) -> SandboxStatus | None ``` サンドボックスの最後に確認されたステータス。

status\_updated\_at

```python theme={"system"} @property def status_updated_at(self) -> datetime | None ``` ステータスが最後に確認されたときのタイムスタンプ。

started\_at

```python theme={"system"} @property def started_at(self) -> datetime | None ``` サンドボックスが開始されたときのタイムスタンプ。

runner\_group\_id

```python theme={"system"} @property def runner_group_id(self) -> str | None ``` サンドボックスが実行されているランナーグループの ID。

service\_urls

```python theme={"system"} @property def service_urls(self) -> tuple[tuple[int, str, str], ...] ``` バックエンドによって割り当てられたサービスごとの URL。

service\_endpoints

```python theme={"system"} @property def service_endpoints(self) -> tuple[HttpsEndpointStatus, ...] ``` create、Get、または list からエコーバックされる HTTPS プロダクトのエンドポイント。

service\_addresses

```python theme={"system"} @property def service_addresses(self) -> tuple[TlsPassthroughEndpointStatus, ...] ``` TLS パススルー エンドポイント が create、Get、または list からエコーバックされます。

containers

```python theme={"system"} @property def containers(self) -> tuple[Container, ...] ``` 作成時のコンテナー仕様で、サンドボックスリソースからエコーバックされたものです。

container\_statuses

```python theme={"system"} @property def container_statuses(self) -> tuple[ContainerStatus, ...] ``` コンテナーごとの観測状態。サンドボックスの `status` はプライマリ所有のままです。

dns\_egress\_names

```python theme={"system"} @property def dns_egress_names(self) -> tuple[str, ...] ``` 作成時に付与されるホスト名で、`status.effective_egress` からエコーバックされます。

effective\_runtime\_class

```python theme={"system"} @property def effective_runtime_class(self) -> str | None ``` バックエンドによって適用された runtime class で、ステータスからエコーバックされたものです。

attached\_volume\_ids

```python theme={"system"} @property def attached_volume_ids(self) -> tuple[str, ...] ``` このサンドボックスに関連付けられた登録済み Volume ID で、ステータスからエコーバックされます。

effective\_egress

```python theme={"system"} @property def effective_egress(self) -> tuple[EgressRule, ...] ``` `status.effective_egress` から反映された有効な外向き通信ルール。

effective\_ingress

```python theme={"system"} @property def effective_ingress(self) -> tuple[IngressRule, ...] ``` `status.effective_ingress` から返される有効なイングレスルールです。

exposed\_ports

```python theme={"system"} @property def exposed_ports(self) -> tuple[tuple[int, str], ...] | None ``` 型付きサービスから導出された `(container_port, name)` ペアを公開します。

resource\_limits

```python theme={"system"} @property def resource_limits(self) -> dict[str, str] | None ``` start 応答からのリソース制限、または検出されたサンドボックスの場合は None。

resource\_requests

```python theme={"system"} @property def resource_requests(self) -> dict[str, str] | None ``` start 応答からのリソースリクエスト、または検出されたサンドボックスの場合は None。

resource\_gpu

```python theme={"system"} @property def resource_gpu(self) -> dict[str, Any] | None ``` start 応答で確認された GPU 設定、または検出されたサンドボックス用の None。

file\_system\_snapshot\_id

```python theme={"system"} @property def file_system_snapshot_id(self) -> str | None ``` `stop(snapshot_on_stop=True)` によって生成されたスナップショットの ID。

exec\_stats

```python theme={"system"} @property def exec_stats(self) -> dict[str, int] ``` このサンドボックスの実行統計。

メソッド

run

```python theme={"system"} run(*args: str = (), container_image: str | None = None, defaults: SandboxDefaults | None = None, auth: AuthConfig | None = None, request_timeout_seconds: float | None = None, poll_retry_budget_seconds: float | None = None, poll_rpc_timeout_seconds: float | None = None, max_lifetime_seconds: float | None = None, tags: list[str] | None = None, profile_ids: list[str] | None = None, profile_names: list[str] | None = None, runner_ids: list[str] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, mounted_files: list[dict[str, Any]] | None = None, s3_mount: dict[str, Any] | None = None, ports: list[dict[str, Any]] | None = None, network: NetworkOptions | dict[str, Any] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, max_timeout_seconds: int | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, services: list[Service] | tuple[Service, ...] | None = None, volumes: list[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | tuple[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any], ...] | None = None, template_id: str | None = None, image_pull_credentials: ImagePullCredentials | dict[str, Any] | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, environment_variables: dict[str, str] | None = None, annotations: dict[str, str] | None = None, secrets: Sequence[Secret | dict[str, Any]] | None = None, data_plane_mode: DataPlaneMode | str | None = None, containers: Sequence[Container | Mapping[str, Any]] | None = None) -> Sandbox ``` サンドボックスを作成して起動し、バックエンドがリクエストを受け入れた時点ですぐに制御を返します。 RUNNING ステータスになるまでは待機しません。準備完了になるまでブロックするには .wait() を使用します。 位置引数が指定された場合、最初の引数がコマンドとなり、残りは そのコマンドの引数になります。引数が指定されない場合は、シェルでシグナルをトラップするデフォルトのキープアライブ処理を使用します。 この処理は、停止時に SIGTERM に応答します。 **パラメーター** * `*args` (`str`): オプションのコマンドと引数 (例: "echo", "hello", "world") 。省略した場合は、SandboxDefaults のデフォルトコマンドを使用します。 * `container_image` (`str | None`): 使用するコンテナーイメージ * `defaults` (`SandboxDefaults | None`): 適用する SandboxDefaults (オプション) * `auth` (`AuthConfig | None`): 認証モードまたはプロバイダー。`defaults.auth` を上書きします。 * `request_timeout_seconds` (`float | None`): API リクエストのタイムアウト (クライアント側) * `poll_retry_budget_seconds` (`float | None`): サンドボックスのステータスをポーリングするループで、一時的なエラーを再試行する際の実時間の予算 (デフォルト: 30 秒) 。0 に設定すると再試行が無効になります。 * `poll_rpc_timeout_seconds` (`float | None`): ポーリング用 Get RPC の呼び出しごとのタイムアウト (デフォルト: 15 秒) 。request\_timeout\_seconds とは別に設定します。 * `max_lifetime_seconds` (`float | None`): サンドボックスの最大ライフタイム (サーバー側) * `tags` (`list[str] | None`): サンドボックスに付与するタグ (オプション) * `profile_ids` (`list[str] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。 * `profile_names` (`list[str] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。 * `runner_ids` (`list[str] | None`): CKS ランナーの固定指定 (オプション。サーバーレスおよび `placement_spillover='serverless_then_cks'` とは併用できません) 。 * `resources` (`ResourceOptions | dict[str, Any] | None`): リソース設定。リクエストと制限を個別に指定する場合は ResourceOptions を、後方互換性のある Guaranteed QoS を使用する場合はフラットな dict を受け入れます。 * `mounted_files` (`list[dict[str, Any]] | None`): 起動時にサンドボックスにマウントするファイル。各 dict には `mount_path` (str) と `file_content` (bytes) が必要です。注: マウントされたファイルは実行時には読み取り専用です。ファイルを変更するには、サンドボックスの起動後に `sandbox.write_file()` を使用してください。 * `s3_mount` (`dict[str, Any] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。 * `ports` (`list[dict[str, Any]] | None`): 1.x で削除されました。代わりに `services=[Service(...)]` を使用してください。 * `network` (`NetworkOptions | dict[str, Any] | None`): 拒否フラグと、作成時に指定するホスト名グラント (オプション、`egress=[EgressRule(dns_name=...)]`) を含む `NetworkOptions` (または dict) 。ポートの公開には `services=` を使用します。 * `placement_mode` (`PlacementMode | str | None`): `PlacementMode` または string (`serverless` / `cks`) 。 * `placement_spillover` (`PlacementSpillover | str | None`): `PlacementSpillover` または string。デフォルトは `strict` です。`Sandbox.__init__` を参照してください。 * `services` (`list[Service] | tuple[Service, ...] | None`): 型付きのサービスポート (`Service` のリストまたはタプル) 。 * `volumes` (`list[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | tuple[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any], ...] | None`): スクラッチボリュームまたは登録済み Volume (`ScratchVolumeOptions`、`RegisteredVolumeOptions`、または `volume_id` を含む dict) 。 * `runtime_class` (`str | None`): ランタイムクラスの固定指定 (オプション。例: `"gvisor"`) 。 * `security_context` (`SecurityContext | dict[str, Any] | None`): プライマリコンテナーのゲスト内権限。 * `working_dir` (`str | None`): プライマリコンテナーのコマンドを実行する作業ディレクトリ。 * `object_storage_access` (`ObjectStorageAccess | dict[str, Any] | None`): オブジェクトストレージの一時的な認証情報。 * `file_system_snapshot` (`FileSystemSnapshotOptions | dict[str, Any] | None`): 単一マウント用の簡易 FSS オプション (`FileSystemSnapshotOptions` または dict) 。複数ボリューム構成では `volumes=` の使用を推奨します。 * `max_timeout_seconds` (`int | None`): 1.x で削除されました。`request_timeout_seconds` を使用してください。 * `environment_variables` (`dict[str, str] | None`): サンドボックスに注入する環境変数。session のデフォルトとマージされ、一致するキーは上書きされます。機密性のない設定にのみ使用してください。 * `annotations` (`dict[str, str] | None`): サンドボックス用の Kubernetes Pod アノテーション。session のデフォルトとマージされ、一致するキーは上書きされます。機密性のないメタデータにのみ使用してください。 * `secrets` (`Sequence[Secret | dict[str, Any]] | None`): 作成時に環境変数として注入するシークレット。デフォルトとマージされます (デフォルトが先に適用され、その後にこのリストが適用されます) 。 * `data_plane_mode` (`DataPlaneMode | str | None`): exec、ログ、ファイル操作のトランスポートポリシー。`auto` の場合は直接 mTLS を優先し、利用できない場合はゲートウェイにフォールバックします。 * `containers` (`Sequence[Container | Mapping[str, Any]] | None`): マルチコンテナー spec。位置引数の command/args、および `container_image`、`resources`、`mounted_files`、`secrets`、`image_pull_credentials`、`environment_variables`、`security_context`、`working_dir` とは同時に指定できません。このリストは、`SandboxDefaults` 上の同名フィールドも含め、これらの単一コンテナー用フィールドを置き換えます。シークレット、env、working\_dir は各 `Container` に指定してください。 戻り値: Sandbox インスタンス (起動リクエストは送信済みですが、まだ起動中の可能性があります) **サンプル** ```python theme={"system"} # デフォルトを使用（シェルの trap によるキープアライブ） sb = Sandbox.run() # fire-and-forget スタイル sb = Sandbox.run("echo", "hello") # sb.sandbox_id は設定済みですが、サンドボックスはまだ起動中の可能性があります # 必要に応じて準備完了まで待機 sb = Sandbox.run("sleep", "infinity").wait() result = sb.exec(["echo", "hello"]).result() # または、コンテキストマネージャーを使用して自動的にクリーンアップ with Sandbox.run("sleep", "infinity") as sb: result = sb.exec(["echo", "hello"]).result() ```

run\_from\_template

```python theme={"system"} run_from_template(template_id: str, *args: str = (), command: str | None = None, defaults: SandboxDefaults | None = None, **kwargs: Any = {}) -> Sandbox ``` 組織テンプレートからサンドボックスを作成します (CreateSandboxFromTemplate)。 **パラメーター** * `template_id` (`str`): 組織スコープのテンプレート UUID。 * `*args` (`str`): コマンド引数を上書きする場合に指定します (オプション)。`command` を指定しなくても適用されます。単一コンテナーに対する部分的なオーバーレイには、この場合も `container_image` が必要です。 * `command` (`str | None`): コマンドを上書きする場合に指定します (オプション)。`containers=` でリスト全体を置き換える場合を除き、`container_image` が必要です。 * `defaults` (`SandboxDefaults | None`): SandboxDefaults (オプション)。 * `**kwargs` (`Any`): `run()` と同じ、作成時の高度な kwargs。`container_image` を渡すと、テンプレートのコンテナー全体 (command、args、env、files、resources、名 `main`) が置き換えられます。既存の設定を取得してマージする処理は行われません。`containers=` はリスト全体を置き換えるため、`container_image` は不要です。その他のコンテナーフィールドのオーバーレイ (`command`、`args`、`environment_variables`、`secrets`、`resources`、`mounted_files`、`volumes`、`file_system_snapshot`、`image_pull_credentials`、`security_context`、`working_dir`) には、`containers=` でリストを置き換える場合を除き、`container_image` が必要です。これは、API がコンテナーリスト全体を置き換え、部分的なパッチを拒否するためです。セッションおよびデフォルトのタグはマージされたうえで、指定時に置き換える上書きとして送信されます。これにより、`list()`/`adopt` でサンドボックスを検索できます。環境変数とアノテーションはテンプレート側で管理されるため、マージされません。 **戻り値** * `Sandbox`: サンドボックスハンドル (遅延起動)。

run\_from\_file

```python theme={"system"} run_from_file(contents: str | Path | bytes, *, primary_service: str, file_type: SandboxFileType | str = SandboxFileType.COMPOSE, image_overrides: Mapping[str, str] | None = None, default_resources: ResourceOptions | dict[str, Any] | None = None, defaults: SandboxDefaults | None = None, auth: AuthConfig | None = None, request_timeout_seconds: float | None = None, poll_retry_budget_seconds: float | None = None, poll_rpc_timeout_seconds: float | None = None, max_lifetime_seconds: float | None = None, tags: list[str] | None = None, runner_ids: list[str] | None = None, network: NetworkOptions | dict[str, Any] | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, annotations: dict[str, str] | None = None, request_id: str | None = None, data_plane_mode: DataPlaneMode | str | None = None, **kwargs: Any = {}) -> Sandbox ``` アップロードしたファイルからサンドボックスを作成します (CreateSandboxFromFile)。 v1 では Compose のみ、プル専用のイメージのみに対応します。`contents` を生のバイト列として読み取り、 YAML の正規化は行いません。同じ `request_id` でバイト列が異なる場合 (空白のみの編集を含む) は `CWSANDBOX_REQUEST_ID_CONFLICT` になります。 バックエンドがリクエストを受け入れるとすぐに制御を返します。RUNNING になるまで待機するには `wait()` を使用してください。 `PREPARING` を待機しないでください。 GetSandbox が返すのは変換後の spec であり、ソースファイルではありません。Compose の `build:` が残っている場合は `CWSANDBOX_NOT_IMPLEMENTED` になります。ビルドをスキップするには、 YAML で `image:` を設定するか、`image_overrides` を使用してください。 **パラメーター** * `contents` (`str | Path | bytes`): Compose ファイルパス (`str` / `Path`) または生の YAML バイト列。`str` は常にパスとして開かれます。Compose のテキストを渡す場合は `bytes` (`.encode("utf-8")`) にしてください。上限は 256 KiB です。バイト列はそのまま送信されます。 * `primary_service` (`str`): サンドボックスのプライマリとなる Compose サービス。 * `file_type` (`SandboxFileType | str`): ドキュメントのタイプ。デフォルトは `compose` です。 * `image_overrides` (`Mapping[str, str] | None`): サービスごとのプル可能なイメージの ref。キーは `contents` 内に存在するサービスである必要があります。 * `default_resources` (`ResourceOptions | dict[str, Any] | None`): `deploy.resources` が省略された各サービスにコピーされる CPU/メモリ。コンテナーごとの値であり、project の予算ではありません。GPU はローカルで拒否されます (ゲートウェイでも拒否されます)。 * `defaults` (`SandboxDefaults | None`): オプションの `SandboxDefaults`。タグ、ネットワーク、`placement_mode`、`runner_ids`、アノテーション、オブジェクトストレージへのアクセス、最大有効期間が継承されます。コンテナー/ボリューム/サービスのデフォルトは継承されません。defaults で指定された非 strict の `placement_spillover` は無視されます (from-file は常に strict です)。キーワード引数で非 strict を明示的に指定すると例外が送出されます。 * `request_id` (`str | None`): オプションのべき等性トークン。省略すると自動生成されます。 * `**kwargs` (`Any`): 拒否されます。この RPC は、ボリューム、パブリッシュされたサービス、`runtime_class`、`image_pull_credentials`、`network_ids`、`build_contexts` を受け入れません。 **戻り値** * `Sandbox`: サンドボックスハンドル (作成リクエストは受け入れ済みですが、まだ起動中の場合があります)。

session

```python theme={"system"} session(defaults: SandboxDefaults | Mapping[str, Any] | None = None, *, auth: AuthConfig | None = None) -> Session ``` 複数のサンドボックスを管理するためのセッションを作成します。 セッションには次の機能があります。 * デフォルトによる設定の共有 * 孤立したサンドボックスの自動クリーンアップ * @session.function() デコレーターによる関数の実行 **パラメーター** * `defaults` (`SandboxDefaults | Mapping[str, Any] | None`): セッション経由で作成されるサンドボックスに適用するデフォルト (オプション) * `auth` (`AuthConfig | None`): 認証方式、解決済みのヘッダー、またはプロバイダー。指定した場合は `defaults.auth` を上書きします。 **戻り値** * `Session`: Session インスタンス **サンプル** ```python theme={"system"} session = Sandbox.session(defaults) sb = session.create(command="sleep", args=["infinity"]) @session.function() def compute(x, y): return x + y await session.close() ```

list

```python theme={"system"} list(*, tags: list[str] | None = None, status: str | None = None, profile_ids: list[str] | None = None, profile_names: list[str] | None = None, runner_ids: list[str] | None = None, show_terminated: bool = False, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None, poll_retry_budget_seconds: float | None = None, poll_rpc_timeout_seconds: float | None = None, data_plane_mode: DataPlaneMode | str = DataPlaneMode.AUTO, volume_ids: list[str] | tuple[str, ...] | None = None) -> OperationRef[list[Sandbox]] ``` オプションのフィルターを使用して既存のサンドボックスを一覧表示します。 exec()、stop()、get\_status()、read\_file()、write\_file() などの操作に使用できる Sandbox インスタンスに解決される OperationRef を返します。 デフォルトでは、実行中 (非ターミナル) のサンドボックスのみが返されます。 `show_terminated=True` を設定すると、終了状態の サンドボックス (完了、失敗、終了) を含むように検索を拡大します。 ターミナルステータスのフィルター (例: `status="completed"`) も、 検索を自動的に拡大します。 **パラメーター** * `tags` (`list[str] | None`): タグでフィルター (サンドボックスは指定されたすべてのタグを持つ必要があります) * `status` (`str | None`): ステータスでフィルター ("running"、"completed"、"failed" など) * `profile_ids` (`list[str] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。 * `profile_names` (`list[str] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。 * `runner_ids` (`list[str] | None`): ランナー ID でフィルター * `volume_ids` (`list[str] | tuple[str, ...] | None`): これらの登録済み Volume ID に関連付けられたサンドボックスにフィルター * `show_terminated` (`bool`): True の場合、終了状態のサンドボックス (完了、失敗、終了) を含めます。デフォルトは False です。 * `base_url` (`str | None`): API URL をオーバーライドします (デフォルト: CWSANDBOX\_BASE\_URL 環境変数またはデフォルト) * `auth` (`AuthConfig | None`): このリクエストの認証方式、解決済みヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300 秒) * `poll_retry_budget_seconds` (`float | None`): サンドボックスステータスのポーリングループで一時的なエラーを再試行するための実時間の予算 (デフォルト: 30 秒) 。再試行を無効にするには 0 に設定します。返される Sandbox インスタンスに適用されます。 * `poll_rpc_timeout_seconds` (`float | None`): ポーリング用 Get RPC の呼び出しごとのタイムアウト (デフォルト: 15 秒) 。`timeout_seconds` とは別です。返される Sandbox インスタンスに適用されます。 * `data_plane_mode` (`DataPlaneMode | str`): 返されるサンドボックスに適用されるトランスポートポリシー。 **戻り値** * `OperationRef[list[Sandbox]]`: OperationRef\[list\[Sandbox]]: 結果をブロックするには .result() を使用します。 * `OperationRef[list[Sandbox]]`: または非同期コンテキストで直接 await します。 **サンプル** ```python theme={"system"} # 同期での使用 - 実行中のサンドボックスのみ（デフォルト） sandboxes = Sandbox.list(tags=["my-batch-job"]).result() for sb in sandboxes: print(f"{sb.sandbox_id}: {sb.status}") sb.stop().result() # 停止したサンドボックスも含める all_sandboxes = Sandbox.list( tags=["my-batch-job"], show_terminated=True ).result() # Async での使用 sandboxes = await Sandbox.list(status="running") for sb in sandboxes: result = await sb.exec(["echo", "hello"]) ```

from\_id

```python theme={"system"} from_id(sandbox_id: str, *, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None, poll_retry_budget_seconds: float | None = None, poll_rpc_timeout_seconds: float | None = None, data_plane_mode: DataPlaneMode | str = DataPlaneMode.AUTO) -> OperationRef[Sandbox] ``` ID を指定して既存のサンドボックスにアタッチします。 既存のサンドボックスに接続された Sandbox インスタンスを作成し、 exec()、stop()、get\_status() などの操作を実行できるようにします。 **パラメーター** * `sandbox_id` (`str`): 既存のサンドボックスの ID * `base_url` (`str | None`): API URL をオーバーライドします (デフォルト: CWSANDBOX\_BASE\_URL 環境変数またはデフォルト値) * `auth` (`AuthConfig | None`): このリクエストに使用する認証方式、解決済みのヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300s) * `poll_retry_budget_seconds` (`float | None`): サンドボックスステータスのポーリングループで一時的なエラーを再試行する際の実時間の予算 (デフォルト: 30s) 。0 に設定すると再試行が無効になります。返される Sandbox インスタンスに適用されます。 * `poll_rpc_timeout_seconds` (`float | None`): ポーリング用 Get RPC の呼び出しごとのタイムアウト (デフォルト: 15s) 。`timeout_seconds` とは別の設定です。返される Sandbox インスタンスに適用されます。 * `data_plane_mode` (`DataPlaneMode | str`): 返されるサンドボックスに適用されるトランスポートポリシー。 **戻り値** * `OperationRef[Sandbox]`: OperationRef\[Sandbox]: .result() を使用すると、ブロックして Sandbox インスタンスを取得できます。 * `OperationRef[Sandbox]`: 非同期コンテキストでは直接 await することもできます。 **送出される例外** * `SandboxNotFoundError`: サンドボックスが存在しない場合 **サンプル** ```python theme={"system"} # 同期での使用例 sb = Sandbox.from_id("sandbox-abc123").result() result = sb.exec(["python", "-c", "print('hello')"]).result() sb.stop().result() # Async での使用例 sb = await Sandbox.from_id("sandbox-abc123") result = await sb.exec(["python", "-c", "print('hello')"]) ```

delete

```python theme={"system"} delete(sandbox_id: str, *, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None, missing_ok: bool = False) -> OperationRef[None] ``` Sandbox インスタンスを作成せずに、ID を指定してサンドボックスを削除します。 これは、サンドボックスに対して他の操作を実行する必要がない クリーンアップのシナリオ向けの便利なメソッドです。 **パラメーター** * `sandbox_id` (`str`): 削除するサンドボックスの ID * `base_url` (`str | None`): API URL をオーバーライドします (デフォルト: CWSANDBOX\_BASE\_URL 環境変数またはデフォルト値) * `auth` (`AuthConfig | None`): このリクエストに使用する認証方式、解決済みヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300 秒) * `missing_ok` (`bool`): True の場合、サンドボックスが存在しないときに SandboxNotFoundError を抑制します。 **戻り値** * `OperationRef[None]`: OperationRef\[None]: 完了するまでブロックするには .result() を使用します。 * `OperationRef[None]`: 見つからない場合は SandboxNotFoundError を送出します (missing\_ok=True の場合を除く)。 * `OperationRef[None]`: 削除に失敗した場合は SandboxError を送出します。 **送出される例外** * `SandboxNotFoundError`: サンドボックスが存在せず、missing\_ok=False の場合 * `SandboxError`: その他の理由で削除に失敗した場合 **サンプル** ```python theme={"system"} # 同期での使用 Sandbox.delete("sandbox-abc123").result() # すでに削除されている場合は無視する Sandbox.delete("sandbox-abc123", missing_ok=True).result() # Async での使用 await Sandbox.delete("sandbox-abc123") ```

get\_snapshot

```python theme={"system"} get_snapshot(file_system_snapshot_id: str, *, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None) -> OperationRef[FileSystemSnapshot] ``` ID を指定して、ファイルシステムスナップショット (FSS) レコードを取得します。 スナップショットは組織スコープです。どのサンドボックスで作成されたかにかかわらず、組織が所有するすべてのスナップショットを 参照できます。 **パラメーター** * `file_system_snapshot_id` (`str`): 取得するスナップショットの ID。 * `base_url` (`str | None`): API URL をオーバーライドする (デフォルト: 環境変数 CWSANDBOX\_BASE\_URL、またはデフォルト値)。 * `auth` (`AuthConfig | None`): このリクエストに使用する認証方式、解決済みのヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300 秒)。 **戻り値** * `OperationRef[FileSystemSnapshot]`: OperationRef\[FileSystemSnapshot]: .result() を使用してブロックするか、await します。 * `OperationRef[FileSystemSnapshot]`: スナップショットが存在しない場合は SnapshotNotFoundError を送出します。 **サンプル** ```python theme={"system"} snap = Sandbox.get_snapshot("fss-abc123").result() print(snap.status, snap.size_bytes) ```

list\_snapshots

```python theme={"system"} list_snapshots(*, source_sandbox_id: str | None = None, status: FileSystemSnapshotStatus | str | None = None, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None) -> OperationRef[list[FileSystemSnapshot]] ``` 組織のファイルシステムスナップショット (FSS) を一覧表示します。 スナップショットは組織スコープで、一覧は自動的にページ分割されます。 `source_sandbox_id` と `status` のフィルターはクライアント側で適用されるため (バックエンドの list RPC はフィルタリングを行いません)、フィルタリングの前に すべてのスナップショットが取得されます。 **パラメーター** * `source_sandbox_id` (`str | None`): 指定した場合、このサンドボックスから取得されたスナップショットのみを返します。 * `status` (`FileSystemSnapshotStatus | str | None`): 指定した場合、このステータスのスナップショットのみを返します (FileSystemSnapshotStatus またはその string 値)。 * `base_url` (`str | None`): API URL をオーバーライドします (デフォルト: CWSANDBOX\_BASE\_URL 環境変数、またはデフォルト値)。 * `auth` (`AuthConfig | None`): このリクエストに使用する認証方式、解決済みヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300 秒)。 **戻り値** * `OperationRef[list[FileSystemSnapshot]]`: OperationRef\[list\[FileSystemSnapshot]]: .result() でブロックして待機するか、await を使用します。 **サンプル** ```python theme={"system"} # 指定したサンドボックスから取得した、準備完了状態のスナップショットをすべて一覧表示 snaps = Sandbox.list_snapshots( source_sandbox_id=sb.sandbox_id, status=FileSystemSnapshotStatus.READY, ).result() ```

delete\_snapshot

```python theme={"system"} delete_snapshot(file_system_snapshot_id: str, *, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None, missing_ok: bool = False) -> OperationRef[None] ``` ID を指定してファイルシステムスナップショット (FSS) を削除します。 スナップショットを削除しても、そのスナップショットからすでにリストアされたサンドボックスには影響しません。 **パラメーター** * `file_system_snapshot_id` (`str`): 削除するスナップショットの ID。 * `base_url` (`str | None`): API URL をオーバーライドします (デフォルト: CWSANDBOX\_BASE\_URL 環境変数、またはデフォルト値)。 * `auth` (`AuthConfig | None`): このリクエストに使用する認証方式、解決済みヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300s)。 * `missing_ok` (`bool`): True の場合、スナップショットが存在しない (すでに削除されている) ときに SnapshotNotFoundError を抑制します。 **戻り値** * `OperationRef[None]`: OperationRef\[None]: .result() を使用して、ブロックまたは await します。 * `OperationRef[None]`: スナップショットが見つからない場合は SnapshotNotFoundError を送出します (missing\_ok=True の場合を除く)。 **サンプル** ```python theme={"system"} Sandbox.delete_snapshot("fss-abc123").result() Sandbox.delete_snapshot("fss-abc123", missing_ok=True).result() ```

get\_snapshot\_bucket\_config

```python theme={"system"} get_snapshot_bucket_config(*, base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None) -> OperationRef[FileSystemSnapshotBucketConfig] ``` 組織の FSS オブジェクトストレージバケットの設定を取得します。 **パラメーター** * `base_url` (`str | None`): API URL をオーバーライドします (デフォルト: CWSANDBOX\_BASE\_URL 環境変数、またはデフォルト値)。 * `auth` (`AuthConfig | None`): このリクエストで使用する認証方式、解決済みヘッダー、またはプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300 秒)。 **戻り値** * `OperationRef[FileSystemSnapshotBucketConfig]`: OperationRef\[FileSystemSnapshotBucketConfig]: .result() または await を使用して結果を取得します。 **サンプル** ```python theme={"system"} cfg = Sandbox.get_snapshot_bucket_config().result() print(cfg.mode, cfg.effective_bucket_name) ```

set\_snapshot\_bucket\_config

```python theme={"system"} set_snapshot_bucket_config(*, bucket_name: str, region: str = '', base_url: str | None = None, auth: AuthConfig | None = None, timeout_seconds: float | None = None) -> OperationRef[FileSystemSnapshotBucketConfig] ``` 組織の FSS オブジェクトストレージバケットの設定を行います。 `bucket_name` を指定して独自のバケットを使用します。空文字列を渡すと CoreWeave 管理のバケットに戻ります。これは管理者限定の操作です。 **パラメーター** * `bucket_name` (`str`): スナップショットをアーカイブする先のバケット。空文字列は CoreWeave 管理のバケットに戻します。 * `region` (`str`): バケットのリージョン (一部のプロバイダーで BYO バケットに必要)。 * `base_url` (`str | None`): オーバーライドする API URL (デフォルト: CWSANDBOX\_BASE\_URL 環境変数またはデフォルト)。 * `auth` (`AuthConfig | None`): 認証方式、解決済みヘッダー、またはこのリクエストのプロバイダー。 * `timeout_seconds` (`float | None`): リクエストのタイムアウト (デフォルト: 300s)。 **戻り値** * `OperationRef[FileSystemSnapshotBucketConfig]`: OperationRef\[FileSystemSnapshotBucketConfig]: 更新された設定。 **サンプル** ```python theme={"system"} # 独自のバケットを使用する Sandbox.set_snapshot_bucket_config( bucket_name="my-org-fss", region="us-east-1" ).result() # CoreWeave が管理するバケットに戻す Sandbox.set_snapshot_bucket_config(bucket_name="").result() ```

get\_status

```python theme={"system"} get_status() -> SandboxStatus ``` サンドボックスの現在のステータスを取得します。 終端状態のサンドボックス (COMPLETED/FAILED/TERMINATED) の場合は、呼び出しを行わずにキャッシュされた ステータスを返します。実行中のサンドボックスの場合は、バックエンドから取得します。 **戻り値** * `SandboxStatus`: SandboxStatus 列挙値 **送出される例外** * `SandboxNotRunningError`: サンドボックスが開始されていない場合 **サンプル** ```python theme={"system"} sb = Sandbox.run("sleep", "10") status = sb.get_status() print(f"Sandbox is {status}") # SandboxStatus.PENDING または RUNNING ```

start

```python theme={"system"} start() -> OperationRef[None] ``` StartSandbox をバックエンドに送信し、OperationRef を即座に返します。 RUNNING ステータスになるまで待機しません。準備完了になるまでブロックするには wait() を使用します。 起動リクエストが受け入れられるまでブロックするには、.result() を呼び出します。 **戻り値** * `OperationRef[None]`: OperationRef\[None]: バックエンドが受け入れるまでブロックするには、.result() を使用します。 **サンプル** ```python theme={"system"} sandbox = Sandbox(command="sleep", args=["infinity"]) sandbox.start().result() print(f"Started sandbox: {sandbox.sandbox_id}") sandbox.wait() # RUNNING になるまでブロックします ```

wait

```python theme={"system"} wait(timeout: float | None = None) -> Sandbox ``` サンドボックスが RUNNING または終端状態に達するまでブロックします。 サンドボックスが RUNNING になるか、すでに完了している (COMPLETED/UNSPECIFIED) 場合に制御を返します。 **パラメーター** * `timeout` (`float | None`): 待機する最大秒数。None の場合はデフォルトのタイムアウトを使用します。 **戻り値** * `Sandbox`: メソッドチェーン用の Self。最終的な状態を判断するには .status を確認してください。 **送出される例外** * `SandboxFailedError`: サンドボックスの起動に失敗した場合 * `SandboxTerminatedError`: サンドボックスが外部から終了された場合 * `SandboxTimeoutError`: タイムアウト時間が経過した場合 **サンプル** ```python theme={"system"} sb = Sandbox.run("sleep", "infinity").wait() result = sb.exec(["echo", "ready"]).result() ```

wait\_until\_complete

```python theme={"system"} wait_until_complete(timeout: float | None = None, *, raise_on_termination: bool = True) -> OperationRef[Sandbox] ``` サンドボックスが終端状態 (COMPLETED/FAILED/TERMINATED) に達するまで待機します。 サンドボックスが終端状態に達したときに解決される OperationRef を返します。 解決後、バックエンドが記録した場合は `returncode` が利用可能になります (`None` のままになるケースについては `returncode` プロパティを参照してください)。 **パラメーター** * `timeout` (`float | None`): 待機する最大秒数。None の場合はデフォルトのタイムアウトを使用します。 * `raise_on_termination` (`bool`): True (デフォルト) の場合、このクライアントが stop() を呼び出したか、バックエンドがレガシーな TERMINATED ステータスを report したときに SandboxTerminatedError が送出されます。COMPLETED となる外部からの強制終了 (インフラストラクチャー、有効期間の制限、他のクライアント) は、バックエンドが termination\_reason メタデータを提供するまで検出できません。SandboxTerminatedError を完全に抑制するには False に設定します。 **戻り値** * `OperationRef[Sandbox]`: OperationRef\[Sandbox]: ブロックするか、非同期コンテキストで await するには `.result()` を使用します。 **送出される例外** * `SandboxTimeoutError`: タイムアウトの期限が切れた場合 * `SandboxTerminatedError`: サンドボックスがこのクライアントによって停止されたか、バックエンドによって TERMINATED として report された場合 (かつ raise\_on\_termination=True の場合) * `SandboxFailedError`: サンドボックスが失敗した場合 **注:** `poll_retry_budget_seconds` は、ユーザーの `timeout` パラメーター内にある厳密なサブタイムアウトです。30秒の再試行予算と300秒のユーザータイムアウトを設定した場合、30秒付近で予算枯渇エラーが発生する可能性があります。より長い再試行を希望する呼び出し元は、それに応じて `poll_retry_budget_seconds` を設定する必要があります。 **サンプル** ```python theme={"system"} sb = Sandbox.run("python", "-c", "print('done')") sb.wait_until_complete().result() print(f"Exit code: {sb.returncode}") ```

stop

```python theme={"system"} stop(*, snapshot_on_stop: bool = False, graceful_shutdown_seconds: float = DEFAULT_GRACEFUL_SHUTDOWN_SECONDS, missing_ok: bool = False, wait_for_ready: bool = True, request_id: str | None = None) -> OperationRef[None] ``` サンドボックスを停止し、すぐに OperationRef を返します。 サンドボックスは、終端状態 (COMPLETED または FAILED) に到達する前に、TERMINATING (猶予期間のドレイン) 状態を経由します。返される OperationRef は、単に stop RPC が成功した時点ではなく、バックエンドが終端状態を確認した時点で解決されます。 複数の呼び出し元は、基盤となる同じ停止タスクを共有します。最初の呼び出し元がタスクを作成し、後続の呼び出し元がそれに参加します。サンドボックスがすでに停止中である、すでに停止している、または通常の `stop()` がすでに実行中であるという理由で、スナップショットを取得しない停止に参加 (または監視) することになる `snapshot_on_stop=True` リクエストは、アーカイブなしで暗黙のうちに完了するのではなく、`SnapshotOnStopConflictError` を送出します。通常の停止は常に結合されます。 サンドボックスはもはや使用できないため、停止が成功したかどうかに関係なく、セッションから登録解除されます。 **パラメーター** * `snapshot_on_stop` (`bool`): True の場合、シャットダウン前に、設定されたマウントのファイルシステムスナップショット (FSS) を取得します。結果のスナップショット ID は、返された OperationRef が解決された後、`file_system_snapshot_id` プロパティを介して利用できます。サンドボックスが `file_system_snapshot` マウントで開始されており、組織で FSS が有効になっている必要があります。スナップショットを取得しない停止がすでに進行中の場合、`SnapshotOnStopConflictError` が送出されます。 * `graceful_shutdown_seconds` (`float`): 正常なシャットダウンを待機する時間です。`snapshot_on_stop=True` の場合、これはアーカイブ後の Pod 削除の猶予期間であり、スナップショットの完了*後*に適用されます。そのため、クライアントの期限はアーカイブの予算とこの猶予期間をカバーします。v1 では、`grace_period_seconds=0` は即時終了を意味します (バックエンドの猶予期間の代替はありません)。バックエンドは、snapshot-on-stop の場合、これを 300 秒に制限します。 * `missing_ok` (`bool`): True の場合、サンドボックスが存在しないときに SandboxNotFoundError を抑制します。`snapshot_on_stop=True` の場合、フラグは引き続き `allow_missing` として送信されます。サンドボックスが見つからない場合、またはサーバーがその組み合わせを拒否した場合、アーカイブなしで成功するのではなく、`SnapshotOnStopConflictError` が送出されます。 * `wait_for_ready` (`bool`): `snapshot_on_stop` が True の場合、停止が完了する前に、スナップショットが READY (または FAILED) に到達するまでブロックします。`snapshot_on_stop` が False の場合は無視されます。 * `request_id` (`str | None`): 再試行時に snapshot-on-stop リクエストを重複排除するための、オプションのクライアント提供キーです。`snapshot_on_stop` が False の場合は無視されます。 **戻り値** * `OperationRef[None]`: OperationRef\[None]: 終端状態になるまでブロックするには .result() を使用します。 * `OperationRef[None]`: 失敗した場合は SandboxError が、見つからない場合は SandboxNotFoundError が送出されます。 * `OperationRef[None]`: (missing\_ok=True の場合を除く)。 **サンプル** ```python theme={"system"} sb.stop().result() # 終了状態（COMPLETED/FAILED）になるまでブロックします # すでに削除されている場合は無視します sb.stop(missing_ok=True).result() # 停止時に設定されたマウントのスナップショットを取得し、その後IDを読み取ります sb.stop(snapshot_on_stop=True).result() file_system_snapshot_id = sb.file_system_snapshot_id # stop() 後の wait_until_complete() は、終了状態になったときに解決されます sb.stop() sb.wait_until_complete().result() # TERMINATING の間ポーリングします ```

snapshot

```python theme={"system"} snapshot(*, wait_for_ready: bool = True, request_id: str | None = None) -> OperationRef[str] ``` 設定されたマウントのファイルシステムスナップショット (FSS) を取得します。 実行中のサンドボックス上で、サンドボックスを停止することなく、`file_system_snapshot` を介して設定されたディレクトリのスナップショットを作成します。サンドボックスがまだ開始されていない場合は、最初にサンドボックスを開始します。`Sandbox.run(file_system_snapshot=FileSystemSnapshotOptions(..., file_system_snapshot_id=))` を使用して、スナップショットを新しいサンドボックスにリストアします。 サンドボックスが `file_system_snapshot` マウントで開始されており、組織で FSS が有効になっている必要があります。 **パラメーター** * `wait_for_ready` (`bool`): スナップショットが READY (または FAILED) に達するまでブロックしてから戻ります。False の場合、スナップショットが作成されると (おそらくまだ CREATING の状態) 戻ります。 * `request_id` (`str | None`): 再試行時にリクエストを重複排除するための、クライアントが提供するオプションのキー。 **戻り値** * `OperationRef[str]`: OperationRef\[str]: `.result()` を使用してブロック (または待機) し、新しい * `OperationRef[str]`: スナップショットの ID を取得します。完全なレコード * `OperationRef[str]`: (ステータス、サイズ、タイムスタンプ) を取得するには、`Sandbox.get_snapshot(id)` を呼び出します。 **送出される例外** * `SandboxSnapshotError`: スナップショットが失敗した場合 (組織で有効になっていない場合の `NOT_SUPPORTED`、クォータ/サイズなどについては、サブクラスを参照してください)。 **サンプル** ```python theme={"system"} with Sandbox.run( file_system_snapshot=FileSystemSnapshotOptions(mount_path="/workspace"), ) as sb: sb.exec(["sh", "-c", "echo hi > /workspace/note.txt"]).result() snapshot_id = sb.snapshot().result() # 必要に応じてレコード全体を確認します: snap = Sandbox.get_snapshot(snapshot_id).result() ```

exec

```python theme={"system"} exec(command: Sequence[str], *, cwd: str | None = None, check: bool = False, timeout_seconds: float | None = None, stdin: bool = False, container: str | None = None) -> Process ``` コマンドを実行し、すぐに Process を返します。 メモ: サンドボックスがまだ RUNNING ではない場合、このメソッドはまず RUNNING になるのを待機します。 timeout\_seconds パラメーターはコマンドの実行にのみ適用され、 RUNNING ステータスになるまでの初期待機時間には適用されません。 **パラメーター** * `command` (`Sequence[str]`): 実行するコマンドと引数 * `cwd` (`str | None`): コマンド実行の作業ディレクトリ。絶対パスである必要があります。指定した場合、コマンドはシェルの cd でラップされます。 * `check` (`bool`): True の場合、ゼロ以外のリターンコードで SandboxExecutionError を送出します。 * `timeout_seconds` (`float | None`): コマンド実行のタイムアウト (サンドボックスが RUNNING になった後) 。サンドボックスが RUNNING ステータスになるまでの待機時間は含まれません。 * `stdin` (`bool`): True の場合、stdin ストリーミングを有効にします。Process.stdin は、コマンドに入力を送信できる StreamWriter になります。False (デフォルト) の場合、stdin はすぐに閉じられ、Process.stdin は None になります。 * `container` (`str | None`): exec を実行するコンテナー名。空または None の場合はプライマリをターゲットにします。 **戻り値** * `Process`: ストリーミング stdout/stderr を持つ Process ハンドル。.result() を呼び出してブロックし、 * `Process`: 最終的な ProcessResult を取得するか、.stdout/.stderr を反復処理して * `Process`: リアルタイムの出力を取得します。stdin=True の場合、Process.stdin は StreamWriter になります。 **送出される例外** * `ValueError`: コマンドが空の場合、または cwd が無効 (空または相対パス) な場合 **サンプル** ```python theme={"system"} # 結果を直接取得する process = sb.exec(["echo", "hello"]) result = process.result() print(result.stdout) # 作業ディレクトリを指定する場合 result = sb.exec(["ls", "-la"], cwd="/app").result() # リアルタイムで出力をストリーミングする process = sb.exec(["python", "script.py"]) for line in process.stdout: print(line) result = process.result() # 標準入力のストリーミングを使用する場合 process = sb.exec(["cat"], stdin=True) process.stdin.write(b"hello world").result() process.stdin.close().result() result = process.result() # Async の使用法 result = await sb.exec(["echo", "hello"]) ```

shell

```python theme={"system"} shell(command: Sequence[str] | None = None, *, width: int | None = None, height: int | None = None, container: str | None = None) -> TerminalSession ``` サンドボックスでインタラクティブな TTY セッションを開始します。 インタラクティブなターミナルでの使用に最適化された TerminalSession を返します。 生のバイト出力 (デコード/再エンコードなし)、出力バッファリングなし、および ファイア・アンド・フォーゲットの標準入力 (stdin) を提供します。 **パラメーター** * `command` (`Sequence[str] | None`): 実行するシェルコマンド。デフォルトは \["/bin/bash"] です。\["/bin/sh"] や \["/usr/bin/python3"] のようなシーケンスを受け入れます。 * `width` (`int | None`): 初期ターミナル幅 (列数)。 * `height` (`int | None`): 初期ターミナルの高さ (行数)。 * `container` (`str | None`): TTY セッションのコンテナー名。空または None の場合はプライマリをターゲットにします。 **戻り値** * `TerminalSession`: .output (StreamReader\[bytes]) を持つ TerminalSession ハンドル、 * `TerminalSession`: .stdin (StreamWriter)、および .resize(w, h)。 **送出される例外** * `ValueError`: command が明示的に空の場合。 **例** ```python theme={"system"} session = sandbox.shell(width=80, height=24) session.stdin.writeline("echo hello").result() for chunk in session.output: sys.stdout.buffer.write(chunk) exit_code = session.wait() ```

read\_file

```python theme={"system"} read_file(filepath: str, *, timeout_seconds: float | None = None, container: str | None = None) -> OperationRef[bytes] ``` サンドボックスからファイルを読み取り、すぐに OperationRef を返します。 **パラメーター** * `filepath` (`str`): サンドボックス内のファイルへのパス * `timeout_seconds` (`float | None`): 操作のタイムアウト * `container` (`str | None`): 読み取り元のコンテナー。空または None の場合はプライマリを対象とします。 **戻り値** * `OperationRef[bytes]`: OperationRef\[bytes]: .result() を使用すると、ブロックして内容を取得します。 **動作:** 約 32 MiB までのファイルは、1 回の unary 呼び出しで読み取られます。それより大きいファイル (約 256 MiB まで) は、透過的にストリーミング読み取りへフォールバックします。Sandbox ごとに最初のフォールバック時に一度だけ INFO レベルでログします。サーバーがファイルのサイズを報告した場合、約 256 MiB を超えるファイルは `CWSANDBOX_FILE_TOO_LARGE` で拒否されます。そのようなファイルには `read_file_streaming` を使用してください。どの経路でも、結果全体がメモリに保持されます。クライアントはリモートのサイズを常に事前に把握できるわけではありません (例: バックエンドがサイズ付きの `CWSANDBOX_FILE_TOO_LARGE` ではなくリソース枯渇によって過大な読み取りを通知する場合) 。そのため、非常に大きなファイルでも拒否されずに全体がバッファされることがあります。大きなファイルには `read_file_streaming` を使用して段階的に読み込み、メモリ使用量を抑えることを推奨します。 **送出される例外** * `SandboxFileError`: ファイルがサーバーの上限を超え、かつサーバーがそのサイズを報告した場合は `reason == CWSANDBOX_FILE_TOO_LARGE` で、ストリーミング読み取りの結果がファイルのサイズに満たない場合 (読み取り前のサイズと照合して切り詰めを検出) は `reason == CWSANDBOX_FILE_TRUNCATED` で送出されます。 * `SandboxStreamBackpressureError`: 大きな読み取りがストリーミングにフォールバックし、クライアントの読み取りよりも速く出力が生成された場合に送出されます (SandboxExecutionError のサブクラス) 。 **サンプル** ```python theme={"system"} data = sb.read_file("/output/result.txt").result() ```

write\_file

```python theme={"system"} write_file(filepath: str, contents: bytes, *, timeout_seconds: float | None = None, container: str | None = None) -> OperationRef[None] ``` サンドボックスにファイルを書き込み、直ちに OperationRef を返します。 **パラメーター** * `filepath` (`str`): サンドボックス内のファイルのパス * `contents` (`bytes`): ファイルの内容 (バイト列) * `timeout_seconds` (`float | None`): 操作のタイムアウト * `container` (`str | None`): 書き込み先のコンテナー。空または None の場合はプライマリが対象になります。 **戻り値** * `OperationRef[None]`: OperationRef\[None]: 完了するまでブロックするには .result() を使用します。 **動作:** 約 32 MiB までのペイロードは、1 回の unary 呼び出しで書き込まれます。それより大きいペイロード (約 256 MiB まで) は、透過的にストリーミング書き込みへフォールバックします。このフォールバックが Sandbox ごとに初めて発生した際に、INFO レベルで 1 回だけログされます。約 256 MiB を超えるペイロードは拒否されるため、その場合は `write_file_streaming` を使用してください。 **送出される例外** * `SandboxFileError`: ペイロードがサーバーの上限を超えた場合は、`reason == CWSANDBOX_FILE_TOO_LARGE` 付きで送出されます。また、ストリーミング書き込みが途中で失敗し、不完全なファイルが残っている可能性がある場合にも (この reason なしで) 送出されます。 * `SandboxStreamBackpressureError`: 大きな書き込みがストリーミングにフォールバックした際に、ソースのデータ生成速度が送信速度を上回った場合に送出されます (SandboxExecutionError のサブクラス)。 **サンプル** ```python theme={"system"} sb.write_file("/input/data.txt", b"content").result() ```

write\_file\_streaming

```python theme={"system"} write_file_streaming(filepath: str, source: bytes | Iterable[bytes] | AsyncIterable[bytes], *, timeout_seconds: float | None = None, container: str | None = None) -> OperationRef[None] ``` ペイロード全体をメモリ上に展開せずに、ファイルをサンドボックスへストリーミングします。 ペイロードがおよそ 32 MiB を超える場合や、データがすでにイテレーター (ファイルハンドル、 ジェネレーター、非同期プロデューサー) である場合は、`write_file` ではなくこちらを使用してください。 **パラメーター** * `filepath` (`str`): サンドボックス内の絶対パス。 * `source` (`bytes | Iterable[bytes] | AsyncIterable[bytes]`): `bytes`、同期の `Iterable[bytes]`、または `AsyncIterable[bytes]` 形式のペイロード。入力は送信前に、フレームに収まるサイズのチャンクに分割されます。yield される項目は `bytes`、`bytearray`、または `memoryview` である必要があります。それ以外の型の場合は `TypeError` が送出されます。 * `timeout_seconds` (`float | None`): ストリーミング書き込みの実時間タイムアウト。 **戻り値** * `OperationRef[None]`: `OperationRef[None]`: `.result()` を呼び出すと、完了するまでブロックします。 **送出される例外** * `SandboxStreamBackpressureError`: ソースのデータ生成速度が送信速度を上回り、ストリームが途中で終了した場合。ペースを制御できるソースから yield するか、大きなアップロードを事前にチャンク分割してください。詳しくはこの例外の docstring を参照してください。 **注意事項:** 送信先には直接書き込まれます (一時ファイルへの書き込み後にリネームする方式ではありません) 。ストリームの途中でキャンセルやトランスポートエラーが発生すると、不完全なファイルが残る可能性があります。また、サンドボックスを再起動すると、ストリーミング転送は継続されません。同期ソース (例: `open(...)` で取得したファイルハンドル) はワーカースレッド上で読み取られるため、`read` がブロッキングしても SDK のイベントループは停止しません。非同期ソースは直接 await されます。どちらを使用しても問題ないため、データに合わせて扱いやすい方を選択してください。

read\_file\_streaming

```python theme={"system"} read_file_streaming(filepath: str, *, timeout_seconds: float | None = None, container: str | None = None) -> StreamReader[bytes] ``` ペイロード全体をバッファリングせずに、サンドボックスからファイルをチャンク単位でストリーミングします。 おおよそ 32 MiB を超えるファイルの場合や、ファイルを段階的に処理したい場合 (ディスクへの書き込み、 逐次的なハッシュ計算、1 行ずつの解析など) は、 `read_file` よりもこちらを使用してください。 大きなファイルの場合、SDK は読み取り*前*にファイルのサイズを取得し、 ストリームの終了後に、少なくともそのバイト数が 配信されたことを検証します。配信されたバイト数がそれより少ない場合、イテレーターは理由 `CWSANDBOX_FILE_TRUNCATED` を伴う `SandboxFileError` を送出します。これにより呼び出し元は、 不完全なファイルをそのまま処理することなく、暗黙的な読み取り不足を検出できます。 (読み取り前の サイズを基準にするため、読み取り中に追記されたファイルが切り詰めと 誤認されることはありません。) このチェックは、暗黙的な切り詰めが発生しない小さなファイルではスキップされます。 また、サイズを判定できない場合はベストエフォートで実行されます。 ループでのチャンクの読み取りがファイルのストリーミングより遅い場合 (たとえば 反復処理の合間に時間のかかる処理を行う場合) 、読み取りが `SandboxStreamBackpressureError` で途中で終了することがあります。反復処理は速やかに行い、時間のかかる処理は 読み取りループの外に移してください。詳しくは、この例外の docstring を参照してください。 **パラメーター** * `filepath` (`str`): サンドボックス内の絶対パス。 * `timeout_seconds` (`float | None`): ストリーミング読み取りの実時間タイムアウト。 **戻り値** * `StreamReader[bytes]`: チャンクを順番に生成する `StreamReader[bytes]`。ファイルの終端は * `StreamReader[bytes]`: イテレーターが通常どおり終了することで通知されます。エラー (ファイルが存在しない、 * `StreamReader[bytes]`: アクセス拒否、切り詰め、読み取りが遅すぎる) は、 * `StreamReader[bytes]`: コンシューマーがその位置を越えて反復処理した時点で再送出されます。 **例** ```python theme={"system"} with contextlib.closing(sb.read_file_streaming("/data/big.bin")) as reader: with open("local.bin", "wb") as f: for chunk in reader: f.write(chunk) ``` **注意事項:** ストリーミング転送はサンドボックスの再起動をまたいで継続されません。長時間の転送中に再起動が発生すると、転送はストリームの途中で失敗します。呼び出し側では、リーダーを最後までイテレートするか、リーダーの `close()` を呼び出してください。SDK はガベージコレクション時にバックグラウンドタスクをキャンセルするファイナライザーを登録しますが、明示的にクローズしたほうがリソースを早く解放できます。バーストを平滑化してバックプレッシャーをかけるため、ループに先行して一定量の出力がバッファされますが、これはメモリ使用量の厳密な上限ではありません。ループの処理が遅れるほど、常駐メモリは増加します。読み取りループは軽量に保ち、チャンクごとの時間のかかる処理はループの外に移してください (`examples/large_file_streaming.py` を参照)。

stream\_logs

```python theme={"system"} stream_logs(*, follow: bool = False, tail_lines: int | None = None, since_time: datetime | None = None, timestamps: bool = False, timeout_seconds: float | None = None, container: str | None = None) -> StreamReader[str] ``` サンドボックスのメインプロセスからログをストリーミングします。 サンドボックスの**メインコマンド** (`Sandbox.run()` に渡されたエントリポイント、またはデフォルトのシェルでトラップされた キープアライブ) の stdout/stderr をストリーミングします。`exec()` で開始したコマンドの出力は 含まれ**ません**。それらの出力には `Process.stdout`/`Process.stderr` を使用してください。 .. note:: デフォルトのキープアライブコマンドで作成されたサンドボックスは、 ログを出力しません。ここでログを確認するには、`Sandbox.run()` を呼び出す際に stdout/stderr に書き込むコマンドを渡してください。 ログ行を strings として yield する StreamReader を返します。このメソッドは 即座に制御を返します。StreamReader の反復処理は、データが到着するまで ブロックされます。 **パラメーター** * `follow` (`bool`): True の場合、新しいログを継続的にストリーミングします (`tail -f` と同様) 。False の場合、実行中のサンドボックスから既存のログをストリーミングして終了します。停止したサンドボックスは `StreamLogs` を拒否します。 * `tail_lines` (`int | None`): 取得する最新の行数。None の場合、利用可能なすべての行を返します。 * `since_time` (`datetime | None`): このタイムスタンプ以降のログのみを返します。タイムゾーン情報を持つ必要があり、naive な datetime を指定すると `ValueError` が送出されます。 * `timestamps` (`bool`): True の場合、各行の先頭にサーバーからの ISO 8601 タイムスタンプを付加します。 * `timeout_seconds` (`float | None`): gRPC 呼び出しのクライアント側の期限。デフォルトは、`follow=False` の場合は `request_timeout_seconds`、`follow=True` の場合は `None` (タイムアウトなし) です。 * `container` (`str | None`): ログをストリーミングするコンテナー。空または None の場合はプライマリコンテナーが対象になります。 **戻り値** * `StreamReader[str]`: ログ行を strings として yield する StreamReader。同期的に反復処理するには * `StreamReader[str]`: `for line in reader` を、非同期に反復処理するには * `StreamReader[str]`: `async for line in reader` を使用します。 **送出される例外** * `SandboxNotRunningError`: `follow=True` で、サンドボックスが停止している場合。 * `SandboxError`: ログストリームでエラーが発生した場合。 **例** ```python theme={"system"} # ワンショット: 最新のログを取得 for line in sandbox.stream_logs(tail_lines=100): print(line, end="") # フォローモード: 継続的にストリーミング for line in sandbox.stream_logs(follow=True): print(line, end="") # Async での使用例 async for line in sandbox.stream_logs(follow=True): print(line, end="") ```