Full example

​
Overview

In addition to running commands, your AI agent may need to modify or read files on your Devbox. The Runloop Devbox provides full programmatic access to the underlying filesystem, allowing your agent to interact with files as needed.

​
Writing Files to the Devbox

When authoring code, your AI Agent will often need to write files to disk. There are two main methods for this:

​
Writing Small Text Files

You can use write_file_contents to easily write a UTF-8 string to a file on disk. Note that all file paths are relative to the user’s home directory by default. 
curl -X POST \
  'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/write_file_contents' \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path": "/home/user/main.py",
    "contents": "print(\"Hello, World!\")"
  }'

​
Uploading Large or Non-Text Files

For larger files or binary data, you should use the upload_file API, which supports files of any sizes and allows passing non text data: 
curl -X POST \
  'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/upload_file' \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H 'Content-Type: multipart/form-data' \
  -F "path=/home/user/large_data.txt" \
  -F "file=@large_data.txt"

​
Reading Files

Your AI Agent will often also need to read files from the Devbox. There are two main methods for this:

​
Reading Small Text Files

You can use read_file_contents to read the contents of a file on the Devbox as a UTF-8 string. 
curl -X POST \
  'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/read_file_contents' \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path": "/home/user/test_results.txt"
  }'

​
Downloading Large or Non-Text Files

You can also use download_file to download a file from the Devbox directly for large or non-text files. 
curl -X POST \
  'https://api.runloop.ai/v1/devboxes/<YOUR_DEVBOX_ID>/download_file' \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path": "/home/user/large_data.txt"
  }'

​
Best Practices

  1. Prefer to use execute_async wherever possible; timeouts for execute_sync are short and may not be enough for large files.
  2. Always specify the full path when working with files to avoid ambiguity.
  3. Be mindful of file permissions when reading or writing files in different directories.
  4. Use error handling in your AI agent’s code to manage potential issues with file operations, such as “file not found” or “permission denied” errors.
  5. When working with files, prefer to use the asynchronous client if you’re working with Python to avoid timeouts.
By leveraging these file operations, your AI agent can effectively manage code, data, and results within the Runloop Devbox environment.