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

​
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 file.write to easily write a UTF-8 string to a file on disk. Note relative paths are relative to the user’s home directory. Full paths are relative to the root of the filesystem, as you would expect. 
await devbox.file.write(
  file_path="/home/user/main.py",
  contents='print("Hello, World!")'
)

​
Uploading Large Files or Binary Data

For larger text files or binary data, you should use the file.upload API, which supports files of any sizes and allows passing non text data: 
file = open('large_data.txt', 'rb')
await devbox.file.upload(
  file_path="/home/user/large_data.txt",
  file=file
)

​
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 file.read to read the contents of a file on the Devbox as a UTF-8 string. 
contents = await devbox.file.read(
  file_path="/home/user/test_results.txt"
)
print(contents)

​
Downloading Large or Non-Text Files

For large text files and binary data, you can use file.download to download from the Devbox. 
contents = await devbox.file.download(
  file_path="/home/user/large_data.txt"
)
print(contents)

​
Best Practices

  1. When working with files, prefer to use the asynchronous client if you’re working with Python to avoid timeouts.
  2. Avoid ambiguity by using the full file path.
  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.
By leveraging these file operations, your AI agent can effectively manage code, data, and results within the Runloop Devbox environment.