Skip to main content

​
Overview

Objects provide a way to store and manage files, data, and other resources that can be shared across Devboxes or made publicly available. The 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. 
curl -X POST \
  'https://api.runloop.ai/v1/objects' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-data-file.csv",
    "content_type": "text/csv"
  }'

​
Mounting Objects to Devboxes

Objects can be mounted directly to a Devbox filesystem when creating the Devbox using the mounts parameter. This allows you to pre-populate files or data in your Devbox without needing to upload them after creation.

​
Mounting via Devbox Create

When creating a Devbox, you can specify object mounts that will be written to the filesystem during initialization: 
curl -X POST \
  'https://api.runloop.ai/v1/devboxes' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "devbox-with-data",
    "mounts": [
      {
        "type": "object_mount",
        "object_id": "OBJECT_ID",
        "object_path": "/home/user/data.csv"
      }
    ]
  }'

​
Mounting Multiple Objects

You can mount multiple objects to different paths on the same Devbox: 
import os
from runloop_api_client import Runloop

client = Runloop(bearer_token=os.environ.get("RUNLOOP_API_KEY"))

devbox = client.devboxes.create(
    name="multi-data-devbox",
    mounts=[
        {
            "type": "object_mount",
            "object_id": "TRAINING_DATA_OBJECT_ID",
            "object_path": "/home/user/training_data.csv"
        },
        {
            "type": "object_mount",
            "object_id": "CONFIG_OBJECT_ID",
            "object_path": "/home/user/config.json"
        },
        {
            "type": "object_mount",
            "object_id": "MODEL_OBJECT_ID",
            "object_path": "/home/user/model.pkl"
        }
    ]
)
Object paths must be absolute paths (e.g., /home/user/file.txt). If the object is an archive, specify the directory where it should be extracted (e.g., /home/user/archive_dir).

​
Mount Use Cases

Object mounts are particularly useful for a variety of larger files, including:
  • Pre-loading datasets: Mount training data or test datasets before running experiments
  • Configuration files: Inject configuration files or environment-specific settings
  • Model weights: Load pre-trained model weights or checkpoints
  • Static assets: Include images, templates, or other static resources
  • Shared data: Use the same data across multiple Devboxes by mounting the same object

​
Retrieving Objects

Get details about a specific object, including its metadata and access information. 
curl -X GET \
  'https://api.runloop.ai/v1/objects/OBJECT_ID' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"

​
Listing Objects

Retrieve a list of all objects in your account with optional filtering and pagination. 
curl -X GET \
  'https://api.runloop.ai/v1/objects?limit=20' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"

​
Listing Public Objects

Browse objects that have been made publicly accessible. 
curl -X GET \
  'https://api.runloop.ai/v1/objects/public?limit=20' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"

​
Generating Download URLs

Create secure, time-limited URLs for downloading object content. 
curl -X POST \
  'https://api.runloop.ai/v1/objects/OBJECT_ID/download' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "expires_in_seconds": 3600
  }'

​
Completing Object Upload

Finalize an object upload after the content has been uploaded to the provided URL. 
curl -X POST \
  'https://api.runloop.ai/v1/objects/OBJECT_ID/complete' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

​
Deleting Objects

Remove an object permanently from your account storage. 
curl -X DELETE \
  'https://api.runloop.ai/v1/objects/OBJECT_ID' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"
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
  4. Optimize content types: Set accurate content types for proper handling
    • text/csv for CSV files
    • application/json for JSON data
    • image/png for PNG images

​
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