> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Persistent storage that can be mounted into sandboxes

Volumes are persistent, team scoped filesystems that you can attach to a sandbox at launch.
You can attach a volume to multiple sandboxes, and a volume is synced across writes.

A volume persists even after all sandboxes are stopped, so you can completely isolate your data needs from your sandbox compute.

## Quick Start

1. Create a volume.
2. Mount it when creating a sandbox.
3. Read and write files at the mount path.

<CodeGroup>
  ```typescript Node.js theme={null}
  import { Hyperbrowser } from "@hyperbrowser/sdk";

  const client = new Hyperbrowser({
    apiKey: process.env.HYPERBROWSER_API_KEY,
  });

  // 1) Create volume
  const volume = await client.volumes.create({ name: "my-workspace" });

  // 2) Create sandbox with mounted volume
  const sandbox = await client.sandboxes.create({
    imageName: "node",
    mounts: {
      "/mnt/workspace": {
        id: volume.id,
        type: "rw",
      },
    },
  });

  // 3) Write/read through mounted path
  await sandbox.files.writeText("/mnt/workspace/hello.txt", "hello from volume");
  const text = await sandbox.files.readText("/mnt/workspace/hello.txt");
  console.log(text);
  ```

  ```python Python theme={null}
  from hyperbrowser import Hyperbrowser
  from hyperbrowser.models import CreateSandboxParams, CreateVolumeParams, SandboxVolumeMount

  client = Hyperbrowser(api_key="YOUR_API_KEY")

  # 1) Create volume
  volume = client.volumes.create(CreateVolumeParams(name="my-workspace"))

  # 2) Create sandbox with mounted volume
  sandbox = client.sandboxes.create(
      CreateSandboxParams(
          image_name="node",
          mounts={
              "/mnt/workspace": SandboxVolumeMount(
                  id=volume.id,
                  type="rw",
              )
          },
      )
  )

  # 3) Write/read through mounted path
  sandbox.files.write_text("/mnt/workspace/hello.txt", "hello from volume")
  text = sandbox.files.read_text("/mnt/workspace/hello.txt")
  print(text)
  ```

  ```bash CLI theme={null}
  # 1) Create volume
  volume_id=$(hx --json volume create my-workspace | jq -r '.id')

  # 2) Create sandbox with mounted volume
  sandbox_id=$(hx --json create node --mount "$volume_id:/mnt/workspace" | jq -r '.id')

  # 3) Write/read through mounted path
  hx file write "$sandbox_id" /mnt/workspace/hello.txt --data 'hello from volume'
  hx file cat "$sandbox_id" /mnt/workspace/hello.txt
  ```

  ```bash cURL theme={null}
  # 1) Create volume
  volume_response=$(curl -sS -X POST https://api.hyperbrowser.ai/api/volume \
    -H "x-api-key: $HYPERBROWSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"my-workspace"}')

  volume_id=$(jq -r '.id' <<<"$volume_response")

  # 2) Create sandbox with mounted volume
  curl -X POST https://api.hyperbrowser.ai/api/sandbox \
    -H "x-api-key: $HYPERBROWSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"imageName\": \"node\",
      \"mounts\": {
        \"/mnt/workspace\": {
          \"id\": \"$volume_id\",
          \"type\": \"rw\"
        }
      }
    }"
  ```
</CodeGroup>

## Why Volumes

Use volumes when you need data to outlive a sandbox and be reused later:

* Persistent workspaces for agents.
* Reusable caches across runs.
* Shared read only data mounted into multiple sandboxes over time.

## Volume Lifecycle

* Create volumes via SDKs, volume endpoints, or `hx volume`.
* Mount volumes during sandbox creation
* Access files through the mounted path with normal sandbox filesystem operations.

## In This Section

* [Managing Volumes](/sandboxes/volumes/managing)
* [Mounting Volumes](/sandboxes/volumes/mounting)
* [Read and Write Mounted Volume Data](/sandboxes/volumes/data-access)
* [Volume Patterns](/sandboxes/volumes/patterns)