> ## 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.

# 파일 시스템 스냅샷

> 샌드박스의 작업 디렉터리를 객체 저장소에 스냅샷으로 저장한 후, 이를 새 샌드박스로 복원하거나 포크하세요.

<Note>
  The examples on this page omit `auth`. To authenticate with your W\&B API key, install `cwsandbox[wandb]` and pass `auth=AuthStrategy.WANDB` to `Sandbox.run()`, `Sandbox()`, or `Sandbox.session()`. See [Get started](/products/sandboxes/serverless/get-started).
</Note>

File System Snapshots (FSS) let a sandbox write to a local working directory, capture that directory into object storage as an immutable snapshot, and later restore it into new sandboxes. Use FSS to suspend and resume a sandbox's filesystem across runs, or to fork one snapshot into several sandboxes that then diverge independently.

## How it works

A sandbox with FSS mounts a writable scratch filesystem at a path you choose. The runner backs this mount with an `EmptyDir`, not a direct object storage mount. Snapshot and restore operations copy a tarball between that local filesystem and an organization-scoped object storage bucket.

Each snapshot is a `FileSystemSnapshot` resource identified by a server-assigned `fileSystemSnapshotId`. Snapshots have three defining properties:

* **Immutable**: creating a snapshot writes one archive. Restoring a snapshot never changes the source snapshot, so a later restore always sees the original bytes.
* **Organization-scoped**: you can restore only snapshots created in your own organization. A snapshot ID from another organization is treated as not found.
* **Independent lifecycle**: snapshots are managed separately from sandboxes. Deleting a sandbox does not delete its snapshots, and deleting a snapshot does not affect sandboxes already running from it.

스냅샷이 저장되는 객체 저장소 버킷은 CoreWeave가 프로비저닝하고 관리합니다.

## Start a sandbox with a snapshot mount

A sandbox can start from one of two filesystem sources: a fresh, empty scratch filesystem, or a restore of an existing snapshot.

### Fresh scratch

A fresh scratch filesystem starts empty and can be snapshotted later. Use it for workflows that need writable local state during a run.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from cwsandbox import Sandbox, FileSystemSnapshotOptions

    with Sandbox.run(
        container_image="ubuntu:22.04",
        file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", size="10Gi"),
    ) as sandbox:
        sandbox.exec(["sh", "-c", "echo hello > /work/data.txt"]).result()
    ```
  </Tab>

  <Tab title="HTTP API">
    `fileSystem.mountPath`와 `fileSystem.size`를 설정하세요. 빈 파일 시스템으로 시작하려면 `fileSystemSnapshot`을 지정하지 마세요.

    ```bash theme={"system"}
    curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
      -H "x-wandb-api-key: $WANDB_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "containerImage": "ubuntu:22.04",
        "command": "sleep",
        "args": ["3600"],
        "fileSystem": {
          "mountPath": "/work",
          "size": "10Gi"
        }
      }'
    ```
  </Tab>
</Tabs>

### Restore from a snapshot

A restore starts the filesystem from an existing snapshot. Set the snapshot ID on the mount's snapshot source.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from cwsandbox import Sandbox, FileSystemSnapshotOptions

    with Sandbox.run(
        container_image="ubuntu:22.04",
        file_system_snapshot=FileSystemSnapshotOptions(
            mount_path="/work",
            file_system_snapshot_id="fss_...",
        ),
    ) as sandbox:
        contents = sandbox.exec(["cat", "/work/data.txt"]).result()
        print(contents.stdout)
    ```
  </Tab>

  <Tab title="HTTP API">
    ```bash theme={"system"}
    curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
      -H "x-wandb-api-key: $WANDB_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "containerImage": "ubuntu:22.04",
        "command": "sleep",
        "args": ["3600"],
        "fileSystem": {
          "mountPath": "/work",
          "size": "10Gi",
          "fileSystemSnapshot": {
            "fileSystemSnapshotId": "fss_..."
          }
        }
      }'
    ```
  </Tab>
</Tabs>

A snapshot must be `READY` before you restore it. Restoring a snapshot that is still `CREATING` fails. See [Snapshot status and failures](#snapshot-status-and-failures).

## Take a snapshot

You can capture a snapshot in two ways: on stop, when a sandbox shuts down, and mid-life, from a running sandbox.

### Snapshot on stop

To preserve a sandbox's filesystem when it shuts down, stop the sandbox with snapshot-on-stop enabled. This is the pattern for suspend and resume: stop with a snapshot, then later start a new sandbox that restores it.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    sandbox.stop(snapshot_on_stop=True).result()
    print(sandbox.file_system_snapshot_id)
    ```
  </Tab>

  <Tab title="HTTP API">
    `StopSandbox`는 스냅샷 요청이 수락되면 `fileSystemSnapshotId`를 반환합니다. `waitForReady`를 `true`로 설정하면 호출은 `maxTimeoutSeconds` 범위 내에서 스냅샷이 `READY` 또는 `FAILED` 상태가 될 때까지 대기합니다. 이 옵션을 설정하지 않으면 스냅샷이 아직 `CREATING` 상태일 때 호출이 반환될 수 있습니다. `[SANDBOX-ID]`를 중지할 샌드박스의 ID로 바꾸세요.

    ```bash theme={"system"}
    curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/stop \
      -H "x-wandb-api-key: $WANDB_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "sandboxId": "[SANDBOX-ID]",
        "fileSystemSnapshotOnStop": true,
        "waitForReady": true,
        "idempotencyKey": "stop-[SANDBOX-ID]-snapshot-1",
        "maxTimeoutSeconds": 600
      }'
    ```
  </Tab>
</Tabs>

### Mid-life snapshot

A mid-life snapshot captures a running sandbox without stopping it. The sandbox keeps running afterward.

<Tabs>
  <Tab title="Python">
    `snapshot()` waits until the snapshot is `READY` by default and returns the snapshot ID.

    ```python theme={"system"}
    snapshot_id = sandbox.snapshot().result()
    print(f"Created snapshot {snapshot_id}")
    ```
  </Tab>

  <Tab title="HTTP API">
    `CreateFileSystemSnapshot`은 중지 시 스냅샷과 마찬가지로 `idempotencyKey`, `waitForReady`, `maxTimeoutSeconds` 옵션을 지원합니다. 단, `StopSandbox`와 달리 `waitForReady`의 기본값은 `true`입니다. `[SANDBOX-ID]`를 스냅샷을 생성할 실행 중인 샌드박스의 ID로 바꾸세요.

    ```bash theme={"system"}
    curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/file-system-snapshots \
      -H "x-wandb-api-key: $WANDB_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "sandboxId": "[SANDBOX-ID]",
        "waitForReady": true,
        "maxTimeoutSeconds": 600
      }'
    ```

    `waitForReady`를 `false`로 설정하면 성공 응답은 스냅샷 행이 생성되고 스냅샷 명령이 전달되었다는 의미일 뿐입니다. 아카이브는 아직 `CREATING` 상태일 수 있으며, 나중에 `FAILED` 상태가 될 수도 있습니다. 스냅샷을 복원하기 전에 상태를 폴링하여 확인하세요.
  </Tab>
</Tabs>

## Fork a snapshot

The same snapshot can be restored into more than one sandbox. Because each snapshot is immutable, the restored sandboxes start from identical bytes and then diverge as they write.

1. Create a `READY` snapshot, with either snapshot-on-stop or a mid-life snapshot.
2. Start sandbox A with `fileSystemSnapshotId` set to that snapshot.
3. Start sandbox B with the same `fileSystemSnapshotId`.
4. Writes in sandbox A and sandbox B diverge independently. The source snapshot is unchanged, so a later restore from the same ID still sees the original snapshot, not the writes from either fork.

```python theme={"system"}
from cwsandbox import Sandbox, FileSystemSnapshotOptions

# Restore the same snapshot into two independent sandboxes.
with Sandbox.run(
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id),
) as fork_a, Sandbox.run(
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id),
) as fork_b:
    fork_a.exec(["sh", "-c", "echo a >> /work/data.txt"]).result()
    fork_b.exec(["sh", "-c", "echo b >> /work/data.txt"]).result()
```

## Manage snapshots

List, fetch, and delete snapshots independently of the sandboxes that created them.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from cwsandbox import Sandbox

    # List all snapshots in your organization.
    snapshots = Sandbox.list_snapshots().result()

    # Fetch one snapshot's details.
    snapshot = Sandbox.get_snapshot(snapshot_id).result()
    print(f"{snapshot.file_system_snapshot_id}: {snapshot.size_bytes} bytes")

    # Delete a snapshot. missing_ok makes the call idempotent.
    Sandbox.delete_snapshot(snapshot_id, missing_ok=True).result()
    ```
  </Tab>

  <Tab title="HTTP API">
    `[SNAPSHOT-ID]`를 조회하거나 삭제할 스냅샷의 ID로 바꾸세요.

    ```bash theme={"system"}
    # 조직 범위의 스냅샷 목록을 조회합니다.
    curl https://api.cwsandbox.com/v1beta2/file-system-snapshots \
      -H "x-wandb-api-key: $WANDB_API_KEY"

    # 스냅샷 하나를 조회합니다.
    curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \
      -H "x-wandb-api-key: $WANDB_API_KEY"

    # 스냅샷 하나를 삭제합니다.
    curl -X DELETE https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \
      -H "x-wandb-api-key: $WANDB_API_KEY"
    ```
  </Tab>
</Tabs>

`list_snapshots()`, `get_snapshot()`, `delete_snapshot()`에도 `auth=AuthStrategy.WANDB`를 전달할 수 있습니다.

## Snapshot status and failures

Snapshots are created asynchronously. A snapshot request can succeed and return a `fileSystemSnapshotId` while the archive is still being written, and the snapshot can fail afterward. This happens most often when `waitForReady` is `false`, or when a client timeout occurs while the runner is still archiving.

To check progress, fetch the snapshot and read two fields:

* `status`: the lifecycle state. The terminal values are `READY` and `FAILED`. The HTTP API returns the fully qualified form, such as `FILE_SYSTEM_SNAPSHOT_STATUS_READY`.
* `statusReason`: populated when `status` is `FAILED`, explaining why.

Poll `GetFileSystemSnapshot` until the snapshot reaches `READY` before you restore it. The Python client's `snapshot()` and `get_snapshot()` handle this polling for you when you wait for the result.

The following table lists the common failure reasons and what to do about each.

| Reason | What it means | What to do |
| - | - | - |
| `CWSANDBOX_FSS_BUCKET_PROVISIONING` | The default snapshot bucket is still being provisioned. | Retry shortly. If the error persists, contact support. |
| `CWSANDBOX_FSS_AUTH_FAILED` | Credential exchange or bucket authorization failed. | Retry after the bucket or WIF policy is fixed. Contact support if this is a CoreWeave-managed bucket. |
| `CWSANDBOX_FSS_TRANSPORT_FAILED` | The runner could not reach object storage, or the archive transfer failed. | Retry. If it repeats, contact support with the snapshot ID. |
| `CWSANDBOX_FSS_BACKEND_THROTTLED` | Object storage returned sustained throttling or backend errors. | Retry later. |
| `CWSANDBOX_FSS_CREATE_TIMED_OUT` | The snapshot did not finish inside the configured timeout. | Retry with a higher `maxTimeoutSeconds`, or reduce the data size. |
| `CWSANDBOX_FSS_CANCELED` | The snapshot was canceled, usually by force-deleting the sandbox during in-flight work. | Retry the snapshot if you still need the data. |
| `CWSANDBOX_FSS_QUOTA_EXCEEDED` | The organization hit its snapshot count or storage cap. | Delete unused snapshots, or request a quota increase. |
| `CWSANDBOX_FSS_NOT_READY` | A restore referenced a snapshot that is not `READY`. | Poll until the snapshot is `READY`, or choose a different snapshot. |
| `CWSANDBOX_FSS_NOT_FOUND` | The snapshot does not exist in your organization. | Check the snapshot ID and the organization. |
| `CWSANDBOX_FSS_SIZE_EXCEEDED` | The requested filesystem size exceeds the supported scratch size. | Request a smaller filesystem, or contact support about limits. |

If a runner finishes uploading the archive but cannot record the result, the snapshot row can become `FAILED` even though an object exists in the bucket. Retry the snapshot in this case.

For asynchronous failures, the platform also emits a `sandbox.file_system_snapshot.async_fail` event, so downstream notification systems can react to snapshots that fail after the original call returned.

## Limitations

FSS version 1 provides snapshot-backed local scratch storage. It is not a shared filesystem and does not provide live, multi-writer mounts. Sandboxes do not read or write each other's filesystems while running. They share state only by snapshotting and restoring.

## SDK example

For a complete, runnable Python example that starts a sandbox, takes a mid-life snapshot, forks it, captures a snapshot on stop, and manages snapshots, see [`file_system_snapshots.py`](https://github.com/coreweave/cwsandbox-client/blob/main/examples/file_system_snapshots.py) in the `cwsandbox-client` repository.

## Related resources

* [Volumes](volumes): scratch volumes and registered Volumes that several sandboxes share.
* [Sandbox lifecycle](client/guides/sandbox-lifecycle): how `stop()` and the sandbox states work.
* [Python client](/products/sandboxes/client): install the SDK and explore the API.