Skip to main content
Start with the Runloop Quickstart to use the examples below.

​
Overview

Storage Objects provide a way to store and manage files, data, and other resources that can be shared across Devboxes or made publicly available. The Storage Objects API supports uploading, downloading, listing, and managing access to stored content.

​
Key Features

  • File Storage: Upload and store files of various types and sizes
  • Public/Private Access: Control whether objects are publicly accessible or private
  • Download URLs: Generate secure, time-limited download URLs for objects
  • Cross-Devbox Sharing: Access objects from multiple Devboxes within your account

​
Creating Objects

Upload a new object to store files or data that can be accessed by your Devboxes.

​
Uploading Text Content

content = 'Hello, world!'
filename = 'hello.txt'

storage_object = await runloop.storage_object.upload_from_text(
  content=content, name=filename)
storage_object_id = storage_object.id

const content = 'Hello, world!';
const filename = 'hello.txt';

const storageObject = await runloop.storageObject.uploadFromText(
  content, filename);
const storageObjectId = storageObject.id;

​
Uploading a File

storage_object = await runloop.storage_object.upload_from_file(
  file_path='./hello.txt', name='hello.txt')
storage_object_id = storage_object.id

const storageObject = await runloop.storageObject.uploadFromFile(
  filePath, name);
const storageObjectId = storageObject.id;

​
Uploading and mounting an Archive Object

You can mount an archive object to a Devbox to make it available to the Devbox’s filesystem.
Archive objects are automatically extracted to the specified path.
Supported archive formats:
  • .gz
  • .tar
  • .tgz
  • .tar.gz
# Archive contents:
# file1.txt
# file/file2.txt

storage_object = await runloop.storage_object.uploadFromFile(
  file_path='./archive.tar.gz',
  name='archive.tar.gz'
)

devbox = await runloop.devbox.create(
  name='devbox-with-archive-object',
  mounts=[{
    type='object_mount',
    object_id=storage_object.id,
    object_path='/home/user/archive_dir'
  }]
)

file1_contents = devbox.file.read('/home/user/archive_dir/file1.txt')
file2_contents = devbox.file.read('/home/user/archive_dir/file/file2.txt')
print(f"Archive contents: file1.txt: {file1_contents} file/file2.txt: {file2_contents}")

// Archive contents:
// file1.txt
// file/file2.txt

const storageObject = await runloop.storageObject.uploadFromFile(
  './archive.tar.gz',
  'archive.tar.gz'
);

const devbox = await runloop.devbox.create({
  name: 'devbox-with-archive-object',
  mounts: [{
    type: 'object_mount',
    object_id: storageObject.id,
    object_path: '/home/user/archive_dir'
  }]
});

const file1Contents = await devbox.file.read('/home/user/archive_dir/file1.txt');
const file2Contents = await devbox.file.read('/home/user/archive_dir/file/file2.txt');
console.log(`Archive contents: file1.txt: ${file1Contents} file/file2.txt: ${file2Contents}`);

​
Retrieving Objects

Get details about a specific object, including its metadata and access information. 
storage_object = await runloop.storage_object.from_id('OBJECT_ID')
object_details = await storage_object.getInfo()

print(f"Object name: {object_details.name}")
print(f"Content type: {object_details.content_type}")
print(f"Created: {object_details.created_at}")

const storageObject = await runloop.storageObject.fromId('OBJECT_ID');
const objectDetails = await storageObject.getInfo();

console.log(`Object name: ${objectDetails.name}`);
console.log(`Content type: ${objectDetails.content_type}`);
console.log(`Created: ${objectDetails.created_at}`);

​
Listing Objects

Retrieve a list of all objects in your account with optional filtering and pagination. 
objects_list = await runloop.storage_object.list(limit=20)
print(f"Total objects: {objects_list.total_count}")

for obj in objects_list:
  print(f"- (ID: {obj.id})")
  

const objectsList = await runloop.storageObject.list({ limit: 20 });
console.log(`Total objects: ${objectsList.total_count}`);

objectsList.forEach(object => {
  console.log(`(ID: ${object.id})`);
});

​
Listing Public Objects

Browse objects that have been made publicly accessible. 
public_objects = await runloop.api.objects.listPublic(limit=20)
print(f"Public objects available: {public_objects.total_count}")

for obj in public_objects.objects:
  print(f"- {obj.name} (ID: {obj.id})")
  

const publicObjects = await runloop.api.objects.listPublic({ limit: 20 });
console.log(`Public objects available: ${publicObjects.total_count}`);

publicObjects.objects?.forEach(obj => {
  console.log(`- ${obj.name} (ID: ${obj.id})`);
});

​
Generating Download URLs

Create secure, time-limited URLs for downloading object content. 
secondsToExpire = 3600
storage_object = await runloop.storage_object.fromId('OBJECT_ID')

download_url_info = await storage_object.get_download_url(secondsToExpire)

print(f"Download URL: {download_url_info.url}")
print(f"Expires at: {download_url_info.expires_at}")

const secondsToExpire = 3600;
const storageObject = await runloop.storageObject.fromId('OBJECT_ID')

const downloadUrlInfo = await storageObject.getDownloadUrl(secondsToExpire);

console.log(`Download URL: ${downloadUrlInfo.url}`);
console.log(`Expires at: ${downloadUrlInfo.expires_at}`);

​
Deleting Objects

Remove an object permanently from your account storage. 
storage_object = await runloop.storageObject.fromId('OBJECT_ID');
deleted_object = await storage_object.delete()

print(f"Object deleted: {deleted_object.name}")

const storageObject = await runloop.storageObject.fromId('OBJECT_ID');
const deletedObject = await storageObject.delete();

console.log(`Object deleted: ${deletedObject.name}`);
Deleting an object is permanent and cannot be undone. Any Devboxes or applications relying on this object will no longer be able to access it.

​
Best Practices

​
Storage Guidelines

  1. Use descriptive names: Choose clear, meaningful names for your objects
    • ✅ training-data-2024.csv
    • ❌ data1.csv
  2. Set appropriate access levels: Use public objects only when necessary
    • Private: Sensitive data, internal files
    • Public: Shared resources, documentation
  3. Manage object lifecycle: Regularly review and clean up unused objects

​
Common Use Cases

  • Training Data: Store datasets for AI model training 
    training-dataset-v1.jsonl
validation-data.csv
  • Configuration Files: Share config files across Devboxes 
    app-config.json
environment-vars.env
  • Assets and Resources: Store images, documents, and other files 
    logo.png
documentation.pdf
template.html
  • Backup and Snapshots: Store backup data and snapshots 
    db-backup-2024-01-15.sql
code-snapshot.tar.gz