Skip to content
Cloudflare Docs

Storage

Mount S3-compatible object storage as local filesystem paths for persistent storage across sandbox lifecycles.

Methods

mountBucket()

Mount an S3-compatible bucket as a local directory.

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)
JavaScript
// Mount R2 bucket
await sandbox.mountBucket("my-r2-bucket", "/data", {
  endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
});


// Access mounted bucket
await sandbox.exec("ls", { args: ["/data"] });
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,
});

Throws:

  • MissingCredentialsError - No credentials found in environment or options
  • InvalidMountConfigError - Invalid endpoint, bucket name, or mount path
  • S3FSMountError - Mount operation failed (network, permissions, bucket not found)

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
await sandbox.mountBucket("my-bucket", "/data", { endpoint: "..." });


// Do work
await sandbox.exec("python process.py");


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

Types

MountBucketOptions

Configuration for mounting a bucket.

TypeScript
interface MountBucketOptions {
  endpoint: string;
  provider?: BucketProvider;
  credentials?: BucketCredentials;
  readOnly?: boolean;
  s3fsOptions?: Record<string, string>;
}

Fields:

  • endpoint (required) - S3-compatible endpoint URL

    • R2: https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
    • S3: https://s3.amazonaws.com or regional endpoint
    • GCS: https://storage.googleapis.com

  • provider (optional) - Storage provider hint ('r2' | 's3' | 'gcs')

    • Default: Auto-detected from endpoint URL

  • credentials (optional) - S3 access credentials

    • Default: Uses AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables

  • readOnly (optional) - Mount in read-only mode

    • Default: false

  • 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

The SDK auto-detects the provider from the endpoint URL and applies optimized flags. For other S3-compatible providers (Backblaze, MinIO, etc.), omit this field or use the s3fsOptions parameter for custom configuration.

BucketCredentials

S3-compatible access credentials.

TypeScript
interface BucketCredentials {
  accessKeyId: string;
  secretAccessKey: string;
}
JavaScript
await sandbox.mountBucket("my-bucket", "/data", {
  endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
  credentials: {
    accessKeyId: env.AWS_ACCESS_KEY_ID,
    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
  },
});