---
title: Storage
description: Mount S3-compatible storage buckets into the Sandbox SDK filesystem for persistent data access.
image: https://developers.cloudflare.com/dev-products-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt  
> Use this file to discover all available pages before exploring further.

[Skip to content](#%5Ftop) 

# Storage

Mount S3-compatible storage buckets (R2, S3, GCS) into the sandbox filesystem for persistent data access.

## Methods

### `mountBucket()`

Mount an S3-compatible bucket to a local path in the sandbox.

TypeScript

```

await sandbox.mountBucket(

  bucket: string,

  mountPath: string,

  options: MountBucketOptions

): Promise<void>


```

**Parameters**:

* `bucket` \- Bucket name (e.g., `"my-r2-bucket"`)
* `mountPath` \- Local filesystem path to mount at (e.g., `"/data"`)
* `options` \- Mount configuration (see [MountBucketOptions](#mountbucketoptions))

* [  JavaScript ](#tab-panel-7857)
* [  TypeScript ](#tab-panel-7858)

JavaScript

```

// Mount R2 bucket to /data

await sandbox.mountBucket("my-bucket", "/data", {

  endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",

  provider: "r2",

});


// Read/write files directly

const data = await sandbox.readFile("/data/config.json");

await sandbox.writeFile("/data/results.json", JSON.stringify(data));


// Mount with explicit credentials

await sandbox.mountBucket("my-bucket", "/storage", {

  endpoint: "https://s3.amazonaws.com",

  credentials: {

    accessKeyId: env.AWS_ACCESS_KEY_ID,

    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,

  },

});


// Read-only mount

await sandbox.mountBucket("datasets", "/datasets", {

  endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",

  readOnly: true,

});


// Mount a subdirectory within the bucket

await sandbox.mountBucket("shared-bucket", "/user-data", {

  endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",

  prefix: "/users/user-123/",

});


```

TypeScript

```

// Mount R2 bucket to /data

await sandbox.mountBucket('my-bucket', '/data', {

  endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',

  provider: 'r2'

});


// Read/write files directly

const data = await sandbox.readFile('/data/config.json');

await sandbox.writeFile('/data/results.json', JSON.stringify(data));


// Mount with explicit credentials

await sandbox.mountBucket('my-bucket', '/storage', {

  endpoint: 'https://s3.amazonaws.com',

  credentials: {

    accessKeyId: env.AWS_ACCESS_KEY_ID,

    secretAccessKey: env.AWS_SECRET_ACCESS_KEY

  }

});


// Read-only mount

await sandbox.mountBucket('datasets', '/datasets', {

  endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',

  readOnly: true

});


// Mount a subdirectory within the bucket

await sandbox.mountBucket('shared-bucket', '/user-data', {

  endpoint: 'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com',

  prefix: '/users/user-123/'

});


```

**Throws**:

* `InvalidMountPointError` \- Invalid mount path or conflicts with existing mounts
* `BucketAccessError` \- Bucket does not exist or insufficient permissions

Authentication

Credentials can be provided via:

1. Explicit `credentials` in options
2. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
3. Automatic detection from bound R2 buckets

See the [Mount Buckets guide](https://developers.cloudflare.com/sandbox/guides/mount-buckets/) for detailed authentication options.

### `unmountBucket()`

Unmount a previously mounted bucket.

TypeScript

```

await sandbox.unmountBucket(mountPath: string): Promise<void>


```

**Parameters**:

* `mountPath` \- Path where the bucket is mounted (e.g., `"/data"`)

* [  JavaScript ](#tab-panel-7855)
* [  TypeScript ](#tab-panel-7856)

JavaScript

```

// Mount, process, unmount

await sandbox.mountBucket("data", "/data", { endpoint: "..." });

await sandbox.exec("python process.py");


// Unmount

await sandbox.unmountBucket("/data");


```

TypeScript

```

// Mount, process, unmount

await sandbox.mountBucket('data', '/data', { endpoint: '...' });

await sandbox.exec('python process.py');


// Unmount

await sandbox.unmountBucket('/data');


```

Automatic cleanup

Mounted buckets are automatically unmounted when the container is destroyed.

## Types

### `MountBucketOptions`

TypeScript

```

interface MountBucketOptions {

  endpoint?: string;

  localBucket?: boolean;

  provider?: BucketProvider;

  credentials?: BucketCredentials;

  readOnly?: boolean;

  prefix?: string;

  s3fsOptions?: Record<string, string>;

}


```

**Fields**:

* `endpoint` (required when `localBucket` is `false` or unset) - S3-compatible endpoint URL  
   * R2: `'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'`  
   * S3: `'https://s3.amazonaws.com'`  
   * GCS: `'https://storage.googleapis.com'`
* `localBucket` (optional) - Mount an R2 bucket using the Worker's R2 binding during local development with `wrangler dev`  
   * When `true`, the SDK syncs the R2 binding directly instead of using an S3 endpoint  
   * `endpoint` and `credentials` are not required when this is `true`  
         * `provider` and `s3fsOptions` are not used when this is `true`  
   * Default: `false`
* `provider` (optional) - Storage provider hint  
   * Enables provider-specific optimizations  
   * Values: `'r2'`, `'s3'`, `'gcs'`
* `credentials` (optional) - API credentials  
   * Contains `accessKeyId` and `secretAccessKey`  
   * If not provided, uses environment variables
* `readOnly` (optional) - Mount in read-only mode  
   * Default: `false`
* `prefix` (optional) - Subdirectory within the bucket to mount  
   * When specified, only contents under this prefix are visible at the mount point  
   * Must start and end with `/` (e.g., `/data/uploads/`)  
   * Default: Mount entire bucket
* `s3fsOptions` (optional) - Advanced s3fs mount flags  
   * Example: `{ 'use_cache': '/tmp/cache' }`

### `BucketProvider`

Storage provider hint for automatic s3fs flag optimization.

TypeScript

```

type BucketProvider = "r2" | "s3" | "gcs";


```

* `'r2'` \- Cloudflare R2 (recommended, applies `nomixupload` flag)
* `'s3'` \- Amazon S3
* `'gcs'` \- Google Cloud Storage

## Related resources

* [Mount Buckets guide](https://developers.cloudflare.com/sandbox/guides/mount-buckets/) \- Complete bucket mounting walkthrough
* [Files API](https://developers.cloudflare.com/sandbox/api/files/) \- Read and write files

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/sandbox/","name":"Sandbox SDK"}},{"@type":"ListItem","position":3,"item":{"@id":"/sandbox/api/","name":"API reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/sandbox/api/storage/","name":"Storage"}}]}
```