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

[Skip to content](#main-content)

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

# Storage

Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://mchen-ai-models-sync.previews.developers.cloudflare.com/sandbox/api/storage/index.md)|[Agent setup](https://mchen-ai-models-sync.previews.developers.cloudflare.com/agent-setup/)

Mount S3-compatible storage buckets (R2, S3, GCS) into the sandbox filesystem for persistent data access. `mountBucket()` supports R2 binding mounts, local R2 binding sync during development, and remote S3-compatible endpoint mounts.

## Methods

### `mountBucket()`

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

```ts
await sandbox.mountBucket(
  bucket: string,
  mountPath: string,
  options?: MountBucketOptions
): Promise<void>
```

**Parameters**:

* `bucket` \- Bucket identifier  
  * When `options.endpoint` is omitted, pass the Worker R2 binding name (for example, `"MY_BUCKET"`)
  * When `options.endpoint` is provided, pass the remote bucket name (for example, `"my-r2-bucket"`)
* `mountPath` \- Local filesystem path to mount at (e.g., `"/data"`)
* `options` (optional) - Mount configuration (see [MountBucketOptions](#mountbucketoptions))

```js
// Mount an R2 bucket by Worker binding name
await sandbox.mountBucket("MY_BUCKET", "/data");

// Read/write files directly
const data = await sandbox.readFile("/data/config.json");
await sandbox.writeFile("/data/results.json", JSON.stringify(data));

// Mount a remote S3-compatible bucket, including explicit R2 endpoints
await sandbox.mountBucket("my-bucket", "/storage", {
	endpoint: "https://s3.amazonaws.com",
	credentials: {
		accessKeyId: env.AWS_ACCESS_KEY_ID,
		secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
	},
});

// Mount an R2 bucket during local development with wrangler dev
await sandbox.mountBucket("MY_BUCKET", "/local-data", {
	localBucket: true,
});

// Mount a prefix from an R2 binding
await sandbox.mountBucket("MY_BUCKET", "/user-data", {
	prefix: "/users/user-123",
	readOnly: true,
});
```

```plaintext
// Mount an R2 bucket by Worker binding name
await sandbox.mountBucket('MY_BUCKET', '/data');

// Read/write files directly
const data = await sandbox.readFile('/data/config.json');
await sandbox.writeFile('/data/results.json', JSON.stringify(data));

// Mount a remote S3-compatible bucket, including explicit R2 endpoints
await sandbox.mountBucket('my-bucket', '/storage', {
  endpoint: 'https://s3.amazonaws.com',
  credentials: {
    accessKeyId: env.AWS_ACCESS_KEY_ID,
    secretAccessKey: env.AWS_SECRET_ACCESS_KEY
  }
});

// Mount an R2 bucket during local development with wrangler dev
await sandbox.mountBucket('MY_BUCKET', '/local-data', {
  localBucket: true
});

// Mount a prefix from an R2 binding
await sandbox.mountBucket('MY_BUCKET', '/user-data', {
  prefix: '/users/user-123',
  readOnly: true
});
```

**Throws**:

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

Authentication

Authentication depends on the mount mode:

1. Omit `endpoint` to mount an R2 bucket by Worker binding name in production
2. Set `localBucket: true` to use the same R2 binding during local development
3. Set `endpoint` to mount a remote S3-compatible bucket, then provide explicit `credentials` or rely on environment variables (`R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`)

Endpoint-based mounts remain supported for explicit R2 endpoint configuration and for other S3-compatible providers.

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

### `unmountBucket()`

Unmount a previously mounted bucket.

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

**Parameters**:

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

```js
// Mount, process, unmount
await sandbox.mountBucket("MY_BUCKET", "/data");
await sandbox.exec("python process.py");

// Unmount
await sandbox.unmountBucket("/data");
```

```plaintext
// Mount, process, unmount
await sandbox.mountBucket('MY_BUCKET', '/data');
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`

```ts
interface RemoteMountBucketOptions {
  endpoint: string;
  provider?: BucketProvider;
  credentials?: BucketCredentials;
  credentialProxy?: boolean;
  readOnly?: boolean;
  s3fsOptions?: string[];
  prefix?: string;
}

interface LocalMountBucketOptions {
  localBucket: true;
  prefix?: string;
  readOnly?: boolean;
}

interface R2BindingMountBucketOptions {
  endpoint?: never;
  prefix?: string;
  readOnly?: boolean;
  s3fsOptions?: string[];
}

type MountBucketOptions =
  | RemoteMountBucketOptions
  | LocalMountBucketOptions
  | R2BindingMountBucketOptions;
```

`mountBucket()` supports these three modes:

* **R2 binding mount** \- Omit `endpoint` to mount by Worker binding name in production

  * Uses credential-less egress interception for R2
  * Supports `prefix`, `readOnly`, and `s3fsOptions`
* **Local R2 binding mount** \- Set `localBucket: true` during `wrangler dev`

  * Uses the Worker R2 binding directly through local synchronization
  * Supports `prefix` and `readOnly`
* **Remote endpoint mount** \- Set `endpoint` to mount any S3-compatible provider

  * Supports explicit `credentials` or environment variable auto-detection
  * Set `credentialProxy: true` to keep credentials out of the container (egress interception)
  * Supports `provider`, `prefix`, `readOnly`, and `s3fsOptions`

**Field details**:

* `endpoint` (remote endpoint mode only) - S3-compatible endpoint URL

  * R2: `'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'`
  * S3: `'https://s3.amazonaws.com'`
  * GCS: `'https://storage.googleapis.com'`
* `localBucket` (local development mode only) - 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
* `provider` (remote endpoint mode only) - Storage provider hint

  * Enables provider-specific optimizations
  * Values: `'r2'`, `'s3'`, `'gcs'`
* `credentials` (remote endpoint mode only) - API credentials

  * Contains `accessKeyId` and `secretAccessKey`
  * If not provided, uses environment variables
* `credentialProxy` (remote endpoint mode only) - Route S3 requests through the Durable Object for signing

  * When `true`, credentials are never written to the container's disk. The Durable Object intercepts and re-signs all outbound S3 requests at the network layer before forwarding them upstream.
  * Supports [AWS SigV4 ↗](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) signing for S3-compatible endpoints (including R2) and HMAC signing for Google Cloud Storage
  * Requires `ContainerProxy` to be exported from your Worker entrypoint
  * Default: `false` (backwards compatibility — recommended to set to `true`; will become the default in a future version)
* `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 with `/` (for example, `/data/uploads` or `/data/uploads/`)
  * Default: Mount entire bucket
* `s3fsOptions` (R2 binding and remote endpoint modes only) - Advanced s3fs mount flags

  * Type: `string[]`
  * Example: `['use_cache=/tmp/cache', 'stat_cache_expire=1']`

### `BucketProvider`

Storage provider hint for automatic s3fs flag optimization.

```ts
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://mchen-ai-models-sync.previews.developers.cloudflare.com/sandbox/guides/mount-buckets/) \- Complete bucket mounting walkthrough
* [Files API](https://mchen-ai-models-sync.previews.developers.cloudflare.com/sandbox/api/files/) \- Read and write files

Was this helpful?

YesNo

## On this page

[![](https://mchen-ai-models-sync.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://mchen-ai-models-sync.previews.developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/api/storage/#page","headline":"Storage · Cloudflare Sandbox SDK docs","description":"Mount S3-compatible storage buckets into the Sandbox SDK filesystem for persistent data access.","url":"https://developers.cloudflare.com/sandbox/api/storage/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```