# サンドボックス

> [!NOTE]
> Sandbox API は実験的な機能です。API および動作は、事前の通知なしに変更される場合があります。共有サンドボックスは、同じ信頼境界内のワークロード向けに設計されています。互いに信頼し合わないワークロードには、専用サンドボックスを使用してください。

使い方を学ぶには、[Sandboxesガイド](../guides/sandbox)をご覧ください。

## Sandbox[[huggingface_hub.Sandbox]]

#### huggingface_hub.Sandbox[[huggingface_hub.Sandbox]]

```python
huggingface_hub.Sandbox(id: str, server: _SandboxServer, local_id: str | None, owns_sandbox: bool, owns_server: bool, sandbox_token: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L783)

Hugging Face Jobs上で実行される、隔離されたクラウドマシン。

> [!NOTE]
> Sandbox APIは実験的なものです。APIや動作は、事前の通知なしに変更される場合があります。

[Sandbox.create()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.create) を使用して専用のサンドボックスを作成します（1つのサンドボックスにつき1つのジョブ）。または、[SandboxPool](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxPool) から多数の低コストな共有サンドボックスを取得します。

どこからでも[Sandbox.connect()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.connect)を使用して、実行中のサンドボックスに再接続できます。コンテキストマネージャーとして使用すると、終了時にサンドボックスを終了できます:

```python
>>> from huggingface_hub import Sandbox
>>> with Sandbox.create(image="python:3.12") as sbx:
...     print(sbx.run("python --version").stdout)
```

#### 閉じる[[huggingface_hub.Sandbox.close]]

```python
close()
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1028)

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

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

#### 接続[[huggingface_hub.Sandbox.connect]]

```python
connect(sandbox_id: str, namespace: str | None = None, token: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L952)

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

#### 作成[[huggingface_hub.Sandbox.create]]

```python
create(image: str = 'python:3.12', flavor: str = 'cpu-basic', idle_timeout: int | float | str | None = 600, env: dict[str, typing.Any] | None = None, secrets: dict[str, typing.Any] | None = None, volumes: typing.Optional[typing.List[huggingface_hub._space_api.Volume]] = None, namespace: str | None = None, forward_hf_token: bool = False, labels: dict[str, str] | None = None, start_timeout: float = 120.0, token: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L835)

**パラメータ:**

image (`str`、*任意*、デフォルトは`"python --3.12"`): `/bin/sh` を備えた任意の Docker イメージ（Docker Hub または `hf.co/spaces/...`）。

flavor (`str`、*任意*、デフォルトは`"cpu-basic"`) : ハードウェアのバリエーション。例: `"cpu-basic"`、`"a10g-small"`。`hf jobs hardware`を参照してください。

idle_timeout (`int` または `float` または `str`、*任意*、デフォルトは `600`) : この時間だけアクティビティ（API 呼び出しなし、実行中のプロセスなし）が続くと、自動的にシャットダウンします。デフォルトは 10 分です。`None` を渡すと無効になります。なお、*foreground* コマンドは現在アクティビティとしてカウントされないため、他の API トラフィックがない状態でこの時間より長くかかる単一の `run()` では、その下でサンドボックスがシャットダウンされる可能性があります。長時間かかる単一のコマンドには、タイムアウトを延長するか（または `None` を渡す）してください。

env (`dict[str, Any]`、*任意*) : サンドボックス内で利用可能な環境変数。

secrets (`dict[str, Any]`、*任意*) : シークレット環境変数（サーバー側で暗号化されます）。

volumes (`List[Volume]`, *任意*) : マウントする HF リポジトリ/バケット。[Volume](/docs/huggingface_hub/v2.4.0/ja/package_reference/jobs#huggingface_hub.Volume) を参照してください。

namespace (`str`, *任意*) : 実行するユーザーまたは組織のネームスペース（デフォルトは現在のユーザー）。

forward_hf_token (`bool`、*任意*、デフォルトは`False`) : True の場合、HF トークンが`HF_TOKEN`として注入されます（オプトイン方式）。

labels (`dict[str, str]`, *省略可*) : 基盤となる HF Job に付与するラベル。

start_timeout (`float`、*任意*、デフォルトは`120.0`) : サンドボックスが準備完了になるまで待機する最大秒数。

token (`str`, *任意*) : HFトークンのオーバーライド。

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

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

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

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

#### プロセス[[huggingface_hub.Sandbox.processes]]

```python
processes()
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1202)

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

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

#### proxy_url_for[[huggingface_hub.Sandbox.proxy_url_for]]

```python
proxy_url_for(port: int | str, path: str = '/', scheme: str = 'https://')
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1238)

**パラメータ:**

port (`int` または `str`) : 内部サーバーがリッスンするポート（プール: unix ソケットの `<port>`）。

path (`str`、*任意*、デフォルトは`"/"`) : 内部サーバー内で参照するパス。例: `"/ws"`。

scheme (`str`、*任意*、デフォルトは`"https --//"`): リンクを構築するためのURLスキームです。デフォルトは`"https://"`です。WebSocketクライアントの場合は`"wss://"`を指定してください（プロキシはプロトコルに依存しないため、変更されるのはクライアント側のスキームのみです）。

**戻り値:** `str`

`https://<job_id>--49983.hf.jobs/v1/.../proxy/8000/ws` のような URL(または `scheme="wss://"` を指定した `wss://...`)。

このサンドボックス*内部*で実行されているサーバーをプロキシするパブリック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 ポートをバインドします。(ここで経由せずに、ジョブプロキシ経由でポートを直接公開することもできます。)

例:
```python
>>> 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")
```

#### 実行[[huggingface_hub.Sandbox.run]]

```python
run(cmd: typing.Union[str, typing.List[str]], shell: bool | None = None, env: dict[str, typing.Any] | None = None, cwd: str | None = None, timeout: float | None = None, stdin: str | None = None, on_stdout: typing.Optional[typing.Callable[[str], NoneType]] = None, on_stderr: typing.Optional[typing.Callable[[str], NoneType]] = None, check: bool = True, capture_output: bool = True, background: bool = False)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1075)

**パラメータ:**

cmd (`str` または `List[str]`) : シェルコマンド文字列（`/bin/sh -c` で実行）または argv リスト（直接 exec される）。

shell (`bool`, *任意*) : `cmd` の型から推測するのではなく、実行モードを強制指定します。 `True` の場合は `/bin/sh -c` を介して実行され、`cmd` が文字列である必要があります。 `False` の場合は `cmd` を直接 exec し、argv リストである必要があります。 `None` (デフォルト) の場合は型から推測します。型に依存する落とし穴を避けるため、明示的に設定してください (例: `["echo hi"]` が `"echo hi"` という単一のプログラム名として exec されてしまうこと)。

env (`dict[str, Any]`, *省略可*) : このコマンド用の追加の環境変数。

cwd (`str`, *任意*) : 作業ディレクトリ。

timeout (`float`, *optional*) : この秒数後にコマンド（プロセスグループ全体）を終了します。

stdin (`str`, *任意*) : コマンドの標準入力に書き込むデータ。

on_stdout (`Callable[[str], None]`, *任意*) : 標準出力のチャンクが届くたびに呼び出されるコールバック。

on_stderr (`Callable[[str], None]`, *任意*) : stderr のチャンクが届くたびに呼び出されるコールバック。

check (`bool`、*任意*、デフォルトは`True`) : True の場合、終了コードがゼロ以外の場合に`SandboxCommandError`を発生させます。

capture_output (`bool`、*任意*、デフォルトは`True`) : True の場合、返される結果に stdout/stderr を蓄積します。`on_stdout`/`on_stderr`のみを使用したい場合は`False`を渡してください。この場合、出力はコールバックに渡された後に破棄されるため、数 GB の出力を生成するコマンドでもメモリに収まる必要がありません。その場合、`result.stdout`/`result.stderr`は空になります。

background (`bool`、*任意*、デフォルトは`False`) : True の場合、コマンドをデタッチして開始し、待機して[SandboxCommandResult](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxCommandResult)を返す代わりに、すぐに[SandboxProcess](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxProcess)を返します。

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

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

戻り値: `background=True` の場合は [SandboxProcess](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxProcess)、それ以外の場合は [SandboxCommandResult](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxCommandResult)（`exit_code`、`stdout`、`stderr`、`duration_ms` を含む）。

## SandboxPool[[huggingface_hub.SandboxPool]]

#### huggingface_hub.SandboxPool[[huggingface_hub.SandboxPool]]

```python
huggingface_hub.SandboxPool(image: str = 'python:3.12', flavor: str = 'cpu-basic', sandboxes_per_host: int = 50, warm_up: int = 1, max_hosts: int | None = None, name: str | None = None, idle_timeout: int | float | str | None = 600, namespace: str | None = None, start_timeout: float = 120.0, adopt_hosts: str = 'own', token: str | None = None, _connect_mode: bool = False)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1313)

共有「ホスト」ジョブの群。それぞれが多数のlandlock分離サンドボックスを内包しています。

> [!WARNING]
> Sandbox APIは実験的なものです。APIや動作は、事前の通知なしに変更される場合があります。
>
> **Pooled sandbox は、1 つの信頼境界内のワークロード向けです。** Pooled sandbox は、共有 VM 内の uid と Landlock ルールセットの組み合わせであり、専用の VM ではありません。ホスト上のすべての sandbox は、そのホストの認証トークンと特権付きコントロールプレーンを共有します。プールを使用すると、*ご自身の* コードを低コストで扇出し展開できます。相互に信頼し合わないワークロードには、[Sandbox.create()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.create) を使用してください。これにより、それぞれに専用の VM が割り当てられます。具体的な制約事項は、sandbox の概念ガイドの「既知の制限」セクションに記載されています。

1つのホストは1つの課金対象となるHF Job（VM）です。サンドボックスサーバーを実行し、`sandboxes_per_host`個までの軽量サンドボックスを多重化して実行します。これらはuidとLandlock LSMによって相互に分離されます。これにより、大規模なファンアウトが安価（VMのコストはすべてのサンドボックスで共有されるため）かつ高速（ホストがウォーム状態になると、サンドボックスの作成はプロキシの往復1回程度で済むため）になります。RLロールアウトのような多数の並列CPUサンドボックスに最適です。GPUを使用する場合、または相互に信頼し合わないワークロード間でVMレベルの強力な分離が必要な場合は、代わりに[Sandbox.create()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.create)を使用してください。

コンストラクタは`warm_up`台のホスト（デフォルトは1台）を事前プロビジョニングし、それらが準備完了するまでブロックします。その後、サンドボックスの要求に応じて追加のホストがオンデマンドでプロビジョニングされ、すべて

`close()`（または `idle_timeout` によるアイドル状態）で破棄されます。ユーザーはジョブを管理する必要はありません。

```python
>>> from huggingface_hub import SandboxPool
>>> with SandboxPool(image="python:3.12", flavor="cpu-basic", warm_up=2) as pool:
...     boxes = [pool.create() for _ in range(100)]   # packed across the warm hosts
...     print(boxes[0].run("echo hi").stdout)
hi
```

`create()` は一度に**1つ**のサンドボックスを作成します。新しいホストを起動する前に、まだ空き容量があるホストを再利用するため、ワークが到着するにつれてオンデマンドでスケールアウトします。最初の数回の呼び出しでのコールドスタートを避けるには、`warm_up`（または`warm`）でホストを事前プロビジョニングしてください。ウォームホストはジョブログによって検出されるため、再利用は**プロセス間**でも機能します（同じ`image`/`flavor`/`name`を持つ新しいプールは、

以前のランが残したものをホストします):

```python
>>> pool = SandboxPool(image="python:3.12")
>>> sbx = pool.create()    # finds a warm host (here or in another process), else boots one
```

#### 閉じる[[huggingface_hub.SandboxPool.close]]

```python
close()
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1729)

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

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

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

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

#### 接続[[huggingface_hub.SandboxPool.connect]]

```python
connect(pool_id: str, namespace: str | None = None, adopt_hosts: str = 'own', token: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1494)

**パラメータ:**

pool_id (`str`) : プールが最初に作成された際に返されるID。

namespace (`str`, *任意*) : プールのホストを検索する名前空間（デフォルトは自分のもの）。

adopt_hosts (`str`、*任意*、デフォルトは`"own"`) : 接続可能なホストを指定します。[SandboxPool](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxPool)を参照してください。同じネームスペースの他のメンバーが開始したホストを持つプールに再接続するには、`"namespace"`が必要です。

token (`str`, *任意*) : HFトークンのオーバーライド。

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

`pool_id` でラベル付けされた実行中のホストを検索し、そのホストジョブのスペックと環境変数からプールの設定（image/flavor/density/host-idle）を再構築します。その後、[SandboxPool](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxPool) を返し、`create()` を呼び出してさらにサンドボックスを作成できるようにします。実行中のホストにパッキングするか、ホストが満杯の場合は複製（同じ設定）を起動します。

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

#### 作成[[huggingface_hub.SandboxPool.create]]

```python
create(env: dict[str, typing.Any] | None = None, idle_timeout: int | float | str | None = 600, forward_hf_token: bool = False)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1591)

**パラメータ:**

env (`dict[str, Any]`, *省略可*) : このサンドボックス用の環境変数（各サンドボックスは個別に割り当てられます）。

idle_timeout (`int` または `float` または `str`、*任意*、デフォルトは `600`) : サンドボックスごとのアイドルタイムアウト — この時間だけ不活動（API 呼び出しなし、実行中のプロセスなし）が続くと、サンドボックスはホストから退避されます。ホストのアイドルタイムアウトとは異なります。無効にするには `None` を渡します。

forward_hf_token (`bool`、*任意*、デフォルトは`False`) : True の場合、サンドボックスに HF トークンを`HF_TOKEN`として注入します（オプトイン方式）。専用のサンドボックスの`secrets`とは異なり、プールされたサンドボックスの環境変数は作成時にホストサーバーに配信されるため（ホストジョブには保存されません）、どのジョブのメタデータにも表示されません。

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

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

#### ウォーム[[huggingface_hub.SandboxPool.warm]]

```python
warm(num_hosts: int = 1)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L1564)

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

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

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

## データ構造

### SandboxCommandResult[[huggingface_hub.SandboxCommandResult]]

#### huggingface_hub.SandboxCommandResult[[huggingface_hub.SandboxCommandResult]]

```python
huggingface_hub.SandboxCommandResult(exit_code: int | None, stdout: str, stderr: str, signal: int | None = None, timed_out: bool = False, duration_ms: int = 0)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L191)

[Sandbox.run()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.run)でサンドボックス内で実行されたコマンドの結果。

### SandboxProcess[[huggingface_hub.SandboxProcess]]

#### huggingface_hub.SandboxProcess[[huggingface_hub.SandboxProcess]]

```python
huggingface_hub.SandboxProcess(id: str | None, pid: int, cmd: typing.Union[str, typing.List[str]], _sandbox: Sandbox, tag: str | None = None, started_at_ms: int | None = None, running: bool = True, exit_code: int | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L211)

[Sandbox.run()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.run)`(..., background=True)`でサンドボックス内で開始されたバックグラウンドプロセス。

[Sandbox.processes()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.Sandbox.processes) でサンドボックスのプロセスをリスト表示し、[SandboxProcess.kill()](/docs/huggingface_hub/v2.4.0/ja/package_reference/sandbox#huggingface_hub.SandboxProcess.kill) でプロセスを停止できます。最近完了したプロセスはリストに残ります（サーバーは一定数のみを保持します）。そのため、`running` と `exit_code` を確認することで、プロセスがまだ実行中か、それとも既に終了しているか（リスト表示時点での状態）を判断できます。

#### kill[[huggingface_hub.SandboxProcess.kill]]

```python
kill()
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L235)

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

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

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

### FileEntry[[huggingface_hub._sandbox.FileEntry]]

#### huggingface_hub._sandbox.FileEntry[[huggingface_hub._sandbox.FileEntry]]

```python
huggingface_hub._sandbox.FileEntry(name: str, path: str, type: typing.Literal['file', 'dir', 'symlink'], size: int, mtime_ms: int | None = None, mode: str = '')
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_sandbox.py#L256)

サンドボックス内のファイルまたはディレクトリ。

## エラー

### SandboxError[[huggingface_hub.errors.SandboxError]]

#### huggingface_hub.errors.SandboxError[[huggingface_hub.errors.SandboxError]]

```python
huggingface_hub.errors.SandboxError(message: str, status_code: int | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L598)

**パラメータ:**

status_code : エラーが API レスポンスから発生した場合（例: ファイルが見つからない場合の`404`）、サンドボックス内のサーバーが返した HTTP ステータス。それ以外の場合は`None`。

サンドボックス操作の基底例外（`huggingface_hub.Sandbox`を参照）。

### SandboxCommandError[[huggingface_hub.errors.SandboxCommandError]]

#### huggingface_hub.errors.SandboxCommandError[[huggingface_hub.errors.SandboxCommandError]]

```python
huggingface_hub.errors.SandboxCommandError(cmd, result)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L611)

**パラメータ:**

cmd : 失敗したコマンド。

result : 完全な`SandboxCommandResult`（exit_code、stdout、stderr など）。

サンドボックス内で実行されたコマンドがゼロ以外の終了コードで終了した場合に発生します。