Managing Files

Manage files on Cerebrium persistent storage with CLI upload, download, and list commands, plus global volumes and resizing options up to 1TB.

Cerebrium offers file management through a persistent volume that’s available to all apps in a project. This storage mounts at /persistent-storage and helps store model weights and files efficiently across deployments.

The /persistent-storage directory is not directly accessible during build time. Use the Cerebrium CLI commands or the mounted volume at runtime to manage these files.

Including Files in Deployments

The cerebrium.toml configuration file controls which files become part of the app:

[cerebrium.deployment]
include = [
    "src/*.py",         # Python files in src.
    "config/*.json",    # JSON files in config.
    "requirements.txt"  # Specific files.
]

exclude = [
    "tests/*",          # Skip test files.
    "*.log"            # Skip log files.
]

Files included in deployments must be under 2GB each, with deployments working best for files under 1GB. Larger files should use persistent storage instead.

Managing Persistent Storage

The CLI provides four commands for working with persistent storage.

At runtime, the volume is mounted at /persistent-storage. When using these commands, the Cerebrium CLI does not display the /persistent-storage/ portion of the path.

Persistent storage is managed per region. Files written to /persistent-storage in one region are not guaranteed to be available in other regions; store data that must be available everywhere on global storage. File commands operate on the default region set by cerebrium region set (us-east-1 for new accounts). To target a different region for a single command, pass --region (or -r):

cerebrium ls --region eu-north-1
cerebrium cp model.bin -r eu-north-1

1. Upload files with cerebrium cp:

   # Upload to root directory
   cerebrium cp src_file_name.txt
   
   # Upload to specific location
   cerebrium cp src_file_name.txt dest_file_name.txt
   
   # Upload to directory
   cerebrium cp dir_name sub_folder/
   

2. List files with cerebrium ls:

   # List root contents
   cerebrium ls
   
   # List specific folder
   cerebrium ls sub_folder/
   

3. Remove files with cerebrium rm:

   # Remove a file
   cerebrium rm file_name.txt
   
   # Remove a directory (directory paths must end with a forward slash)
   cerebrium rm folder_name/
   

4. Download files with cerebrium download:

   # Download to current directory with same filename
   cerebrium download file_name.txt
   
   # Download with a different local filename
   cerebrium download file_name.txt local_file_name.txt
   
   # Download from a subdirectory
   cerebrium download sub_folder/file_name.txt
   

Using Stored Files

Access files in persistent storage at runtime:

import os
import torch

# Load a model from persistent storage.
file_path = "/persistent-storage/segment-anything/sam_vit_h_4b8939.pth"
model = torch.jit.load(file_path)

Applications access files using the full /persistent-storage/ path at runtime:

# Read a file from persistent storage
with open("/persistent-storage/data/config.json", "r") as f:
    config = json.load(f)

# Write to persistent storage
with open("/persistent-storage/data/results.json", "w") as f:
    json.dump(results, f)

# Check if file exists in persistent storage
if os.path.exists("/persistent-storage/models/mymodel.pt"):
    model = torch.load("/persistent-storage/models/mymodel.pt")

Remember that while the CLI commands don’t display the /persistent-storage/ prefix in their output, your code must use the full path to access these files at runtime.

Global Storage

Apps deployed with region = "global" mount an additional volume at /global-persistent-storage. It is a single volume shared across every region the app runs in: files written there are visible from all regions, and reads are cached per region. See Multi-Region Deployment.

Manage files on the global volume by passing --region global to the file commands:

cerebrium cp model.bin --region global
cerebrium ls --region global

Use the global volume for data that must be available everywhere, such as model weights for a global app. Use /persistent-storage for region-local data.

The global volume is 1TB. It does not appear in the dashboard Volumes list and cannot be resized.

Increasing Storage Capacity

Persistent volumes can be resized up to 1TB through self-service. Storage costs are listed on the pricing page.

1. Via Dashboard: Navigate to the project and select Volumes. Click the three-dot menu on the volume and select Increase Size.

2. Via API: Use the resize volume endpoint. The volume ID is default-<region>. Sizes range from 50GB to 1TB, and shrinking a volume is not supported:

curl -X PATCH "https://rest.cerebrium.ai/v2/projects/{project_id}/volumes/default-us-east-1/resize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newSizeGb": 200}'

For storage needs beyond 1TB, contact support on Discord or via email.

Using External Cloud Storage

Cerebrium does not mount external cloud storage buckets (S3, GCS, Azure Blob) as a filesystem. To read from or write to your own bucket, use the provider’s SDK inside your app code and authenticate with credentials stored as secrets.

1. Add the SDK to your cerebrium.toml:

   [cerebrium.dependencies.pip]
   boto3 = "latest"
   

2. Store your credentials as project or app secrets (for example AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION). Secrets are exposed as environment variables at runtime.

3. Access the bucket from your handler:

   import os
   import boto3
   
   s3 = boto3.client(
       "s3",
       aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
       aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
       region_name=os.environ.get("AWS_REGION", "us-east-1"),
   )
   
   def predict(key: str):
       s3.download_file("my-bucket", key, f"/persistent-storage/{key}")
       return {"path": f"/persistent-storage/{key}"}
   

For large model weights or datasets, download once into /persistent-storage so subsequent container starts read from the local volume instead of the bucket. The same pattern applies to Google Cloud Storage (google-cloud-storage) and Azure Blob Storage (azure-storage-blob).

Storage Quota Errors

If you hit your storage quota, you’ll see errors like No space left on device when trying to download or write files. To resolve this:

1. Remove unnecessary files from /persistent-storage using cerebrium rm
2. Resize the volume to a larger capacity (up to 1TB self-service)
3. Contact support for storage beyond 1TB