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

# Storage Objects

> Store and manage files and data objects for integration with Devboxes and Blueprints

<Tip>Start with the [Runloop Quickstart](/docs/tutorials/quickstart) to use the examples below.</Tip>

## 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

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  const content = 'Hello, world!';
  const filename = 'hello.txt';

  const storageObject = await runloop.storageObject.uploadFromText(
    content, filename);
  const storageObjectId = storageObject.id;
  ```
</CodeGroup>

### Uploading a File

<CodeGroup>
  ```python Python theme={null}
  storage_object = await runloop.storage_object.upload_from_file(
    file_path='./hello.txt', name='hello.txt')
  storage_object_id = storage_object.id
  ```

  ```typescript TypeScript theme={null}
  const storageObject = await runloop.storageObject.uploadFromFile(
    filePath, name);
  const storageObjectId = storageObject.id;
  ```
</CodeGroup>

### Uploading and mounting an Archive Object

You can mount an archive object to a Devbox to make it available to the Devbox's filesystem.

<Note>
  Archive objects are automatically extracted to the specified path.
</Note>

Supported archive formats:

* .gz
* .tar
* .tgz
* .tar.gz

<CodeGroup>
  ```python Python theme={null}
  # 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}")
  ```

  ```typescript TypeScript theme={null}
  // 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}`);
  ```
</CodeGroup>

## Retrieving Objects

Get details about a specific object, including its metadata and access information.

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  ```
</CodeGroup>

## Listing Objects

Retrieve a list of all objects in your account with optional filtering and pagination.

<CodeGroup>
  ```python Python theme={null}
  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})")
    
  ```

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

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

## Listing Public Objects

Browse objects that have been made publicly accessible.

<CodeGroup>
  ```python Python theme={null}
  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})")
    
  ```

  ```typescript TypeScript theme={null}
  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})`);
  });
  ```
</CodeGroup>

## Generating Download URLs

Create secure, time-limited URLs for downloading object content.

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  ```
</CodeGroup>

## Deleting Objects

Remove an object permanently from your account storage.

<CodeGroup>
  ```python Python theme={null}
  storage_object = await runloop.storageObject.fromId('OBJECT_ID');
  deleted_object = await storage_object.delete()

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

  ```typescript TypeScript theme={null}
  const storageObject = await runloop.storageObject.fromId('OBJECT_ID');
  const deletedObject = await storageObject.delete();

  console.log(`Object deleted: ${deletedObject.name}`);
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## 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
  ```