Storage Objects

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

Use descriptive names: Choose clear, meaningful names for your objects
- ✅ training-data-2024.csv
- ❌ data1.csv
Set appropriate access levels: Use public objects only when necessary
- Private: Sensitive data, internal files
- Public: Shared resources, documentation
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

Overview

Tools

Components

Benchmarks & Evals

Debugging

Overview

Key Features

Creating Objects

Uploading Text Content

Uploading a File

Uploading and mounting an Archive Object

Retrieving Objects

Listing Objects

Listing Public Objects

Generating Download URLs

Deleting Objects

Best Practices

Storage Guidelines

Common Use Cases

​Overview

​Key Features

​Creating Objects

​Uploading Text Content

​Uploading a File

​Uploading and mounting an Archive Object

​Retrieving Objects

​Listing Objects

​Listing Public Objects

​Generating Download URLs

​Deleting Objects

​Best Practices

​Storage Guidelines

​Common Use Cases

Overview

Key Features

Creating Objects

Uploading Text Content

Uploading a File

Uploading and mounting an Archive Object

Retrieving Objects

Listing Objects

Listing Public Objects

Generating Download URLs

Deleting Objects

Best Practices

Storage Guidelines

Common Use Cases