Sandbox - CoreWeave Docs

ソース: src/cwsandbox/_sandbox.py:1688

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

@property
def sandbox_id(self) -> str | None

まだ開始されていない場合は None、それ以外の場合は一意のサンドボックス ID。

returncode

@property
def returncode(self) -> int | None

サンドボックスが完了した場合の終了コード。まだ実行中の場合は None。

runner_id

@property
def runner_id(self) -> str | None

サンドボックスが実行されているランナー。開始されていない場合は None。

status

@property
def status(self) -> SandboxStatus | None

サンドボックスの最後に確認されたステータス。

status_updated_at

@property
def status_updated_at(self) -> datetime | None

ステータスが最後に確認されたときのタイムスタンプ。

started_at

@property
def started_at(self) -> datetime | None

サンドボックスが開始されたときのタイムスタンプ。

runner_group_id

@property
def runner_group_id(self) -> str | None

サンドボックスが実行されているランナーグループの ID。

service_urls

@property
def service_urls(self) -> tuple[tuple[int, str, str], ...]

バックエンドによって割り当てられたサービスごとの URL。

service_endpoints

@property
def service_endpoints(self) -> tuple[HttpsEndpointStatus, ...]

create、Get、または list からエコーバックされる HTTPS プロダクトのエンドポイント。

service_addresses

@property
def service_addresses(self) -> tuple[TlsPassthroughEndpointStatus, ...]

TLS パススルーエンドポイントが create、Get、または list からエコーバックされます。

containers

@property
def containers(self) -> tuple[Container, ...]

作成時のコンテナー仕様で、サンドボックスリソースからエコーバックされたものです。

container_statuses

@property
def container_statuses(self) -> tuple[ContainerStatus, ...]

コンテナーごとの観測状態。サンドボックスの status はプライマリ所有のままです。

dns_egress_names

@property
def dns_egress_names(self) -> tuple[str, ...]

作成時に付与されるホスト名で、status.effective_egress からエコーバックされます。

effective_runtime_class

@property
def effective_runtime_class(self) -> str | None

バックエンドによって適用された runtime class で、ステータスからエコーバックされたものです。

attached_volume_ids

@property
def attached_volume_ids(self) -> tuple[str, ...]

このサンドボックスに関連付けられた登録済み Volume ID で、ステータスからエコーバックされます。

effective_egress

@property
def effective_egress(self) -> tuple[EgressRule, ...]

status.effective_egress から反映された有効な外向き通信ルール。

effective_ingress

@property
def effective_ingress(self) -> tuple[IngressRule, ...]

status.effective_ingress から返される有効なイングレスルールです。

exposed_ports

@property
def exposed_ports(self) -> tuple[tuple[int, str], ...] | None

型付きサービスから導出された (container_port, name) ペアを公開します。

resource_limits

@property
def resource_limits(self) -> dict[str, str] | None

start 応答からのリソース制限、または検出されたサンドボックスの場合は None。

resource_requests

@property
def resource_requests(self) -> dict[str, str] | None

start 応答からのリソースリクエスト、または検出されたサンドボックスの場合は None。

resource_gpu

@property
def resource_gpu(self) -> dict[str, Any] | None

start 応答で確認された GPU 設定、または検出されたサンドボックス用の None。

file_system_snapshot_id

@property
def file_system_snapshot_id(self) -> str | None

stop(snapshot_on_stop=True) によって生成されたスナップショットの ID。

exec_stats

@property
def exec_stats(self) -> dict[str, int]

このサンドボックスの実行統計。

メソッド

run

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 インスタンス (起動リクエストは送信済みですが、まだ起動中の可能性があります) サンプル

# デフォルトを使用（シェルの 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

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

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

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 インスタンス

サンプル

session = Sandbox.session(defaults)
sb = session.create(command="sleep", args=["infinity"])

@session.function()
def compute(x, y):
    return x + y

await session.close()

list

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 します。

サンプル

# 同期での使用 - 実行中のサンドボックスのみ（デフォルト）
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

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: サンドボックスが存在しない場合

サンプル

# 同期での使用例
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

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: その他の理由で削除に失敗した場合

サンプル

# 同期での使用
Sandbox.delete("sandbox-abc123").result()

# すでに削除されている場合は無視する
Sandbox.delete("sandbox-abc123", missing_ok=True).result()

# Async での使用
await Sandbox.delete("sandbox-abc123")

get_snapshot

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 を送出します。

サンプル

snap = Sandbox.get_snapshot("fss-abc123").result()
print(snap.status, snap.size_bytes)

list_snapshots

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 を使用します。

サンプル

# 指定したサンドボックスから取得した、準備完了状態のスナップショットをすべて一覧表示
snaps = Sandbox.list_snapshots(
    source_sandbox_id=sb.sandbox_id,
    status=FileSystemSnapshotStatus.READY,
).result()

delete_snapshot

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 の場合を除く)。

サンプル

Sandbox.delete_snapshot("fss-abc123").result()
Sandbox.delete_snapshot("fss-abc123", missing_ok=True).result()

get_snapshot_bucket_config

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 を使用して結果を取得します。

サンプル

cfg = Sandbox.get_snapshot_bucket_config().result()
print(cfg.mode, cfg.effective_bucket_name)

set_snapshot_bucket_config

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]: 更新された設定。

サンプル

# 独自のバケットを使用する
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

get_status() -> SandboxStatus

サンドボックスの現在のステータスを取得します。終端状態のサンドボックス (COMPLETED/FAILED/TERMINATED) の場合は、呼び出しを行わずにキャッシュされたステータスを返します。実行中のサンドボックスの場合は、バックエンドから取得します。 戻り値

SandboxStatus: SandboxStatus 列挙値

送出される例外

SandboxNotRunningError: サンドボックスが開始されていない場合

サンプル

sb = Sandbox.run("sleep", "10")
status = sb.get_status()
print(f"Sandbox is {status}")  # SandboxStatus.PENDING または RUNNING

start

start() -> OperationRef[None]

StartSandbox をバックエンドに送信し、OperationRef を即座に返します。 RUNNING ステータスになるまで待機しません。準備完了になるまでブロックするには wait() を使用します。起動リクエストが受け入れられるまでブロックするには、.result() を呼び出します。 戻り値

OperationRef[None]: OperationRef[None]: バックエンドが受け入れるまでブロックするには、.result() を使用します。

サンプル

sandbox = Sandbox(command="sleep", args=["infinity"])
sandbox.start().result()
print(f"Started sandbox: {sandbox.sandbox_id}")
sandbox.wait()  # RUNNING になるまでブロックします

wait

wait(timeout: float | None = None) -> Sandbox

サンドボックスが RUNNING または終端状態に達するまでブロックします。サンドボックスが RUNNING になるか、すでに完了している (COMPLETED/UNSPECIFIED) 場合に制御を返します。 パラメーター

timeout (float | None): 待機する最大秒数。None の場合はデフォルトのタイムアウトを使用します。

戻り値

Sandbox: メソッドチェーン用の Self。最終的な状態を判断するには .status を確認してください。

送出される例外

SandboxFailedError: サンドボックスの起動に失敗した場合
SandboxTerminatedError: サンドボックスが外部から終了された場合
SandboxTimeoutError: タイムアウト時間が経過した場合

サンプル

sb = Sandbox.run("sleep", "infinity").wait()
result = sb.exec(["echo", "ready"]).result()

wait_until_complete

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 を設定する必要があります。 サンプル

sb = Sandbox.run("python", "-c", "print('done')")
sb.wait_until_complete().result()
print(f"Exit code: {sb.returncode}")

stop

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 の場合を除く)。

サンプル

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

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=<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、クォータ/サイズなどについては、サブクラスを参照してください)。

サンプル

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

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 が無効 (空または相対パス) な場合

サンプル

# 結果を直接取得する
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

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 が明示的に空の場合。

例

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

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 のサブクラス) 。

サンプル

data = sb.read_file("/output/result.txt").result()

write_file

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 のサブクラス)。

サンプル

sb.write_file("/input/data.txt", b"content").result()

write_file_streaming

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

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]: コンシューマーがその位置を越えて反復処理した時点で再送出されます。

例

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

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: ログストリームでエラーが発生した場合。

例

# ワンショット: 最新のログを取得
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="")

​プロパティ

​sandbox_id

​returncode

​runner_id

​status

​status_updated_at

​started_at

​runner_group_id

​service_urls

​service_endpoints

​service_addresses

​containers

​container_statuses

​dns_egress_names

​effective_runtime_class

​attached_volume_ids

​effective_egress

​effective_ingress

​exposed_ports

​resource_limits

​resource_requests

​resource_gpu

​file_system_snapshot_id

​exec_stats

​メソッド

​run

​run_from_template

​run_from_file

​session

​list

​from_id

​delete

​get_snapshot

​list_snapshots

​delete_snapshot

​get_snapshot_bucket_config

​set_snapshot_bucket_config

​get_status

​start

​wait

​wait_until_complete

​stop

​snapshot

​exec

​shell

​read_file

​write_file

​write_file_streaming

​read_file_streaming

​stream_logs

プロパティ

sandbox_id

returncode

runner_id

status

status_updated_at

started_at

runner_group_id

service_urls

service_endpoints

service_addresses

containers

container_statuses

dns_egress_names

effective_runtime_class

attached_volume_ids

effective_egress

effective_ingress

exposed_ports

resource_limits

resource_requests

resource_gpu

file_system_snapshot_id

exec_stats

メソッド

run

run_from_template

run_from_file

session

list

from_id

delete

get_snapshot

list_snapshots

delete_snapshot

get_snapshot_bucket_config

set_snapshot_bucket_config

get_status

start

wait

wait_until_complete

stop

snapshot

exec

shell

read_file

write_file

write_file_streaming

read_file_streaming

stream_logs