Skip to main content
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.
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 and Install and authenticate.
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.

Ways to use a bucket from a sandbox

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

Cloud provider SDK, CLI or REST API

Use the cloud provider SDK, CLI, or REST API directly.

FUSE mount

Mount the bucket with a FUSE-based filesystem so applications access objects through file paths.
FUSE (Filesystem in Userspace) 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.
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, a FUSE-based filesystem implementation that provides S3 bucket access through standard file operations. The s3fs-fuse package can be installed during template 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.
ppio.Dockerfile
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.

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.
s3fs documents endpoint as the legacy name of region, so endpoint=${AWS_REGION} passes a region name in that option.
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.
Last modified on November 19, 2026