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

# Read and Write Files on a Devbox

> Give your AI agent access to modify and interact with files on your devbox.

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

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

<Tip>
  To inject files at Devbox creation time, use [File Mounts](/docs/devboxes/mounts/file-mounts) instead of writing files after the Devbox starts.
</Tip>

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

<CodeGroup>
  ```python Python theme={null}
  await devbox.file.write(
    file_path="/home/user/main.py",
    contents='print("Hello, World!")'
  )
  ```

  ```typescript TypeScript theme={null}
  await devbox.file.write({
    file_path: '/home/user/main.py',
    contents: 'print("Hello, World!")'
  });
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  file = open('large_data.txt', 'rb')
  await devbox.file.upload(
    file_path="/home/user/large_data.txt",
    file=file
  )
  ```

  ```typescript TypeScript theme={null}
  const file = fs.createReadStream('large_data.txt');
  await devbox.file.upload({
    path: '/home/user/large_data.txt',
    file: file
  });
  ```

  {/* ```bash curl
    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"
    ``` */}
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  contents = await devbox.file.read(
    file_path="/home/user/test_results.txt"
  )
  print(contents)
  ```

  ```typescript TypeScript theme={null}
  const contents = await devbox.file.read({
    file_path: '/home/user/test_results.txt'
  });
  console.log(contents);
  ```
</CodeGroup>

### Downloading Large or Non-Text Files

For large text files and binary data, you can use `file.download` to download from the Devbox.

<CodeGroup>
  ```python Python theme={null}
  contents = await devbox.file.download(
    file_path="/home/user/large_data.txt"
  )
  print(contents)
  ```

  ```typescript TypeScript theme={null}
  const response = await devbox.file.download({
    path: '/home/user/large_data.txt'
  });
  const blob = await response.blob();
  console.log(blob);
  ```

  {/* ```bash curl
    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"
      }'
    ``` */}
</CodeGroup>

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