サンドボックスを終了せずに、ローカルHTTPクライアントを解放します。冪等です。

プールサンドボックスでは何もしません（クライアントはプールのホストに属しているため）。

idのみを使用して、どこからでも実行中のサンドボックスに再接続します。

専用のサンドボックス（1つの HF Job）を作成し、準備が完了するまでブロックします（cpu-basic では約 7 秒）。

各サンドボックスは完全に分離されたVMであるため、GPUワークロードや信頼できないコードの実行には適切な選択です。代わりに、多数の低コストなCPUサンドボックスを分散して実行する場合は、SandboxPoolを使用してください。

ジョブは最大24時間の固定の生存期間で実行されます。idle_timeoutが実際の管理役であり、アイドル状態のサンドボックスはそれよりずっと前に自動的にシャットダウンされます。

イメージには/bin/shのみが必要です。サンドボックスサーバーは、利用可能な場合はwget/curlで起動時にダウンロードされ、利用できない場合は常にマウントされているサーバーバケットから読み込まれます（これによりコールドスタートに約2〜3秒追加されるため、wget/curlを同梱することで高速に保たれます）。

このサンドボックスのバックグラウンドプロセスをリスト表示します。

Sandbox.run()(..., background=True)で開始されたプロセスを返します。SandboxProcess.kill()で1つを停止できます。最近完了したプロセスはリストに保持されます（running=Falseおよびexit_code付き）。サーバーは保持するプロセス数に上限を設けているため、数千の短いコマンドを実行したサンドボックスでも、すべてがリストに表示されることはありません。

このサンドボックス内部で実行されているサーバーをプロキシするパブリックURL。

返されたURLへのリクエストは、ジョブ内のサンドボックスサーバーによって、サンドボックス内でportで起動したサーバーに転送されます。WebSocket(ws(s)://)のアップグレードやストリーミングレスポンスも含まれます。認証にはproxy_headersと組み合わせて使用してください。

サンドボックスがportでリッスンする必要がある方法:

• プール / 共有サンドボックス: TCPポートをバインドできません（Landlock）。そのため、$SBX_PROXY_DIR/<port>.sock に unixソケット をバインドしてください（SBX_PROXY_DIR 環境変数はすべてのサンドボックスで設定されています）。例: uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock。
• 専用サンドボックス: 127.0.0.1:<port> 上で通常の TCP ポートをバインドします。（ここで経由せずに、ジョブプロキシ経由でポートを直接公開することもできます。）

>>> url = sandbox.proxy_url_for(8000, "/ws", scheme="wss://")
>>> import websockets
>>> async with websockets.connect(url, additional_headers=sandbox.proxy_headers) as ws:
...     await ws.send("hello")

サンドボックス内でコマンドを実行し、その完了を待機しながら、出力をライブでストリーミングします。

background=True を指定すると、コマンドはデタッチ状態で開始され、run は完了を待たずに即座に SandboxProcess を返します。これはサーバーやその他の長時間実行されるプロセスに便利です。後で Sandbox.processes() を使用して一覧を表示し、SandboxProcess.kill() を使用して1つを停止できます。ストリーミング/待機専用のオプション（timeout、stdin、on_stdout、on_stderr、check）はこのモードでは適用されません。

戻り値: background=True の場合は SandboxProcess、それ以外の場合は SandboxCommandResult（exit_code、stdout、stderr、duration_ms を含む）。

プールを解放します。冪等です。

作成したプールに対しては、すべてのホストジョブ（したがって、それらのすべてのサンドボックス）を終了します。connect() されたハンドルに対しては、ローカル HTTP クライアントのみを解放します。共有ホストは他のクライアントにサービスを提供している可能性があるため、Sandbox.connect() と同様に、with ブロックを抜けてもそれらを停止してはいけません。接続されたプールのホストは、hf sandbox pool delete <id> を使用して明示的に終了してください。

ホストのこの処理が開始したもののみがキャンセルされます。ラベル経由で検出されたホストは、別のプロセスのサンドボックスを提供している可能性があるため、終了させるのではなく解放されます。

ホストジョブのキャンセルに失敗した場合、SandboxError が発生し、まだ実行中のジョブが特定されます。これらのジョブは課金が継続され、キャッシュエントリが保持されるため、引き続き検出可能になります。__exit__ 経由で例外が既に発生している状態で close() に到達した場合、その失敗はログに記録されるのみであり、元のエラーを隠蔽することはありません。

IDを指定して実行中のプールに再接続します。どのマシンからでも実行でき、ローカル状態は不要です。

pool_id でラベル付けされた実行中のホストを検索し、そのホストジョブのスペックと環境変数からプールの設定（image/flavor/density/host-idle）を再構築します。これにより、SandboxPool が返され、実行中のホストにサンドボックスを詰め込むか、ホストが満杯の場合は複製（同じ設定）を起動して、create() によりさらに多くのサンドボックスを作成する準備が整います。

実行中のホストが見つからない場合、SandboxError を発生させます（プールは、そのホストがすべて消滅した時点で存在しなくなります。アイドルタイムアウトまたは強制終了された場合です）。

必要に応じてホストをプロビジョニングし、1つのサンドボックスを作成します。

空き容量のあるホスト（このプールのもの、またはジョブラベル/ローカルキャッシュ経由で発見されたウォームホスト）を再利用してから新しいホストを起動するため、ウォームホストに対するcreate()のコストは往復1回程度です。ファンアウトのために繰り返し呼び出してください。最初の呼び出しでのコールドスタートを避けるには、warm_up（またはwarm）を使用してホストを事前プロビジョニングしてください。ホストが私たちの下で満杯になった場合（別のプロセスが詰め込んだ場合）や、キャッシュされたホストが存在しなくなった場合、サンドボックスは別のホスト（または新しいホスト）に再配置されます。

num_hosts 個の空のホストが実行されていることを確認し、その状態を維持します。プールのホストのジョブ ID を返します。

プールを事前に「作成」するために使用されます。ホストはプールラベルと設定（環境変数に格納）を保持しているため、後から別のマシンからでもSandboxPool.connect(pool_id)を呼び出すと、それらのホストを見つけ出し、コールドスタートなしでサンドボックスを起動できます。ホストは、停止されるかアイドル状態になるまで課金され続けます。

このプール用にすでに稼働中のホスト（ジョブラベルで特定）を起動前に採用するため、connect() の後の warm()、または warm() の繰り返し呼び出しは、稼働中のホストを重複させたり max_hosts を超えたりするのではなく、num_hosts までホスト数を補完します。

バックグラウンドプロセスを終了します。冪等です。

この呼び出しが停止の原因かどうかを返します: False は、すでに終了または終了処理が行われたことを意味し、これはエラーではありません。

setsid() を呼び出して分離した子プロセスは、シグナルが送信されたプロセスグループから離脱し、この呼び出しよりも長く存続します。起動したすべてのプロセスが終了していることを確実にするためには、サンドボックスを削除してください。