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

# Mount an S3 bucket in a sandbox

> Mount an Amazon S3 bucket inside a sandbox with s3fs-fuse installed in a template Dockerfile, so data outlives the sandbox temporary disk.

Each sandbox is provisioned with ephemeral system disk storage for temporary data. When the sandbox terminates or times out, all data in that storage is purged. Data that must persist belongs in external cloud storage. An object storage bucket can be mounted as a filesystem so applications reach objects through file paths.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

> [!NOTE]
>
> An AWS account with an S3 bucket and IAM credentials that can read and write the bucket is required. Storage allocations and costs are on the [pricing page](https://ppio.ai/pricing).

## Ways to use a bucket from a sandbox

Object storage buckets can be used from a sandbox in two common ways.

> [card] Cloud provider SDK, CLI or REST API
>
> Use the cloud provider SDK, CLI, or REST API directly.

> [card] FUSE mount
>
> Mount the bucket with a FUSE-based filesystem so applications access objects through file paths.

[FUSE (Filesystem in Userspace)](https://www.kernel.org/doc/html/next/filesystems/fuse.html) is a kernel module and userspace library that implements filesystems in userspace applications. It provides an abstraction layer that presents remote cloud storage services as standard filesystem hierarchies, so file operations go through conventional POSIX interfaces.

> [!WARNING]
>
> FUSE-based object storage mounts introduce significant I/O performance overhead from network latency and protocol translation layers. Applications with stringent performance requirements should avoid this approach. FUSE filesystem operations also lack the atomicity guarantees of native object storage APIs, which creates potential race conditions where a local filesystem operation succeeds while the corresponding remote operation fails, leaving the data inconsistent. This mounting approach suits read-heavy workloads with infrequent writes and relaxed performance constraints. For performance-critical applications or frequent write patterns, integrate with the cloud provider SDK or native REST API instead.

## Build a template with s3fs

Amazon S3 buckets can be mounted as POSIX-compliant filesystems with [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse), a FUSE-based filesystem implementation that provides S3 bucket access through standard file operations.

The s3fs-fuse package can be installed during [template](https://docs.ppio.ai/sandbox/templates/overview.md) creation by adding installation commands to the `ppio.Dockerfile`, or installed dynamically in a running sandbox for ad-hoc requirements.

**1. Write the template Dockerfile**

The following `ppio.Dockerfile` installs s3fs-fuse during template building.

```dockerfile ppio.Dockerfile theme={null}
# Compatible with Debian-based distributions
FROM ubuntu:latest

# Critical: s3fs versions below 1.93 contain known mounting issues. Ensure version compatibility.
RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y s3fs
```

**2. Build the template**

Build the template from the Dockerfile and give it a name. The sandbox example reads that name or ID from `TEMPLATE_ID`.

```bash theme={null}
# Build a template from ./ppio.Dockerfile
ppio template create s3fs --from dockerfile
```

## Mount the bucket

Create a sandbox from the template that carries s3fs, then mount the bucket and reach objects through the mount point.

The program creates a sandbox from the template, writes the AWS credentials to the s3fs password file, mounts the bucket, then writes and reads a file through the mount point.

```python Python theme={null}
import os
from ppio_sandbox import PPIO

PPIO_API_KEY = os.environ.get('PPIO_API_KEY')
TEMPLATE_ID = os.environ.get('TEMPLATE_ID')
AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID')
AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY')
AWS_BUCKET_NAME = os.environ.get('AWS_BUCKET_NAME')
AWS_REGION = os.environ.get('AWS_REGION')
if not PPIO_API_KEY or not TEMPLATE_ID or not AWS_ACCESS_KEY_ID or not AWS_SECRET_ACCESS_KEY or not AWS_BUCKET_NAME or not AWS_REGION:
    raise ValueError('Required environment variables not configured: PPIO_API_KEY, TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')

ppio = PPIO(api_key=PPIO_API_KEY)
MOUNT_DIRECTORY = '/mnt/s3-bucket'

sandbox = ppio.sandbox.create(TEMPLATE_ID)

# Initialize mount point directory structure
sandbox.files.make_dir(MOUNT_DIRECTORY)

# Configure s3fs credentials using standard credential file location
# s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
# Custom credential paths require explicit specification via -o passwd_file parameter
sandbox.files.write('/root/.passwd-s3fs', f'{AWS_ACCESS_KEY_ID}:{AWS_SECRET_ACCESS_KEY}')

# Enforce secure credential file permissions (owner read-only)
sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

# Execute S3 bucket mount operation with optimized parameters
# Configuration parameters:
# - allow_other: Enable cross-user filesystem access
# - endpoint: Specify the AWS region endpoint for your bucket
# Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
mount_options = f'allow_other,endpoint={AWS_REGION}'
sandbox.commands.run(f'sudo s3fs {AWS_BUCKET_NAME} {MOUNT_DIRECTORY} -o {mount_options}')

# Validate mount functionality with write operation
sandbox.files.write(f'{MOUNT_DIRECTORY}/test-file.txt', 'test-file-content')

# Verify mount integrity through read operation
content = sandbox.files.read(f'{MOUNT_DIRECTORY}/test-file.txt')
print('File content:', content)

sandbox.kill()
```

```javascript Node.js theme={null}
// index.mts
import { PPIO } from 'ppio-sandbox'

const PPIO_API_KEY = process.env.PPIO_API_KEY
const TEMPLATE_ID = process.env.TEMPLATE_ID
const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME
const AWS_REGION = process.env.AWS_REGION
if (!PPIO_API_KEY || !TEMPLATE_ID || !AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_BUCKET_NAME || !AWS_REGION) {
  throw new Error('Required environment variables not configured: PPIO_API_KEY, TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')
}

const ppio = new PPIO({ apiKey: PPIO_API_KEY })
const MOUNT_DIRECTORY = '/mnt/s3-bucket'

const sandbox = await ppio.sandbox.create(TEMPLATE_ID)

// Initialize mount point directory structure
await sandbox.files.makeDir(MOUNT_DIRECTORY)

// Configure s3fs credentials using standard credential file location
// s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
await sandbox.files.write('/root/.passwd-s3fs', `${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}`)

// Enforce secure credential file permissions (owner read-only)
await sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

// Execute S3 bucket mount operation with optimized parameters
// Configuration parameters:
// - allow_other: Enable cross-user filesystem access
// - endpoint: Specify the AWS region endpoint for your bucket
// Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
const mountOptions = `allow_other,endpoint=${AWS_REGION}`
await sandbox.commands.run(`sudo s3fs ${AWS_BUCKET_NAME} ${MOUNT_DIRECTORY} -o ${mountOptions}`)

// Validate mount functionality with write operation
await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

// Verify mount integrity through read operation
const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
console.log(content)

await sandbox.kill()
```

> [!NOTE]
>
> s3fs documents `endpoint` as the legacy name of `region`, so `endpoint=${AWS_REGION}` passes a region name in that option.

> [!WARNING]
>
> The AWS access key and secret key are written to `/root/.passwd-s3fs` inside the sandbox. The example restricts the file to its owner with `chmod 600`. Any process in the sandbox that can run as root can read them. Remove the file when the credentials should not stay in the sandbox: `sudo rm /root/.passwd-s3fs`.


## Related topics

- [Work with files in a sandbox](https://docs.ppio.ai/sandbox/filesystem/overview.md)
- [Create a sandbox](https://docs.ppio.ai/sandbox/create.md)
- [Kill a sandbox](https://docs.ppio.ai/sandbox/kill.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.