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

# Mounting Volumes

> Attach volumes to sandboxes at launch

Attach existing volumes when you create a sandbox.

## Mount at Sandbox Creation

Use the SDK, CLI or REST API to mount volumes at sandbox creation.

<CodeGroup>
  ```typescript Node.js theme={null}
  const sandbox = await client.sandboxes.create({
    imageName: "node",
    mounts: {
      "/mnt/workspace": {
        id: "550e8400-e29b-41d4-a716-446655440000",
        type: "rw",
      },
      "/mnt/cache": {
        id: "660e8400-e29b-41d4-a716-446655440000",
        type: "ro",
      },
    },
  });
  ```

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

  sandbox = client.sandboxes.create(
      CreateSandboxParams(
          image_name="node",
          mounts={
              "/mnt/workspace": SandboxVolumeMount(
                  id="550e8400-e29b-41d4-a716-446655440000",
                  type="rw",
              ),
              "/mnt/cache": SandboxVolumeMount(
                  id="660e8400-e29b-41d4-a716-446655440000",
                  type="ro",
              ),
          },
      )
  )
  ```

  ```bash CLI theme={null}
  hx vm create node \
    --mount 550e8400-e29b-41d4-a716-446655440000:/mnt/workspace \
    --mount 660e8400-e29b-41d4-a716-446655440000:/mnt/cache:ro
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/sandbox \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "imageName": "node",
      "mounts": {
        "/mnt/workspace": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": "rw"
        },
        "/mnt/cache": {
          "id": "660e8400-e29b-41d4-a716-446655440000",
          "type": "ro"
        }
      }
    }'
  ```
</CodeGroup>

Raw `mounts` payload:

```json theme={null}
{
  "imageName": "node",
  "mounts": {
    "/mnt/workspace": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "rw"
    },
    "/mnt/cache": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "type": "ro"
    }
  }
}
```

## CLI `--mount` Formats

Use repeated `--mount` flags.

```bash theme={null}
<volume-id>:/abs/path[:ro|rw]
```

Examples:

```bash theme={null}
hx vm create node --mount <volume-id>:/mnt/workspace
hx vm create node --mount <volume-id>:/mnt/cache:ro
```

```bash theme={null}
source=<volume-id>,target=/abs/path[,readonly|mode=ro|mode=rw]
```

Examples:

```bash theme={null}
hx vm create node --mount source=<volume-id>,target=/mnt/workspace
hx vm create node --mount source=<volume-id>,target=/mnt/cache,readonly
```

## Mount Object Fields

<ParamField path="mounts.<path>.id" type="string" required>
  Volume ID (UUID).
</ParamField>

<ParamField path="mounts.<path>.type" type="string" default="rw">
  Access mode: `rw` or `ro`.
</ParamField>

## Naming Rules

* Mount path must be absolute and below `/`.
* Mount path cannot be `/`.
* Mount path must already be normalized.
* Mount path cannot target protected system locations such as `/etc`, `/usr`, `/proc`, `/dev`, `/root`, `/run`, or `/sys`.
* Duplicate mount targets are rejected.
* Volume must exist and belong to your team.

## Launch Behavior

At launch, Hyperbrowser resolves each mount to a team-owned volume, then provisions runtime mount instructions with scoped access.

If mount resolution fails, sandbox creation fails.

<Warning>
  Mounts are currently configured at sandbox launch. Updating mounts on an
  already running sandbox is not supported
</Warning>

## Next Step

* Continue to [Read and Write Mounted Volume Data](/sandboxes/volumes/data-access).