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

# Reading

> Read text and binary files from sandboxes. Learn how to read file contents from HopX sandboxes using Python and JavaScript SDKs or REST API. Includes examples for reading text files, binary files, handling encoding, and processing file contents in your applications.

Read files from your sandbox filesystem. HopX supports both text and binary file reading with automatic encoding handling.

## Overview

File reading is essential for:

* Accessing generated outputs from code execution
* Reading configuration files
* Processing data files
* Retrieving logs and results

<Note>
  Files can be read from allowed paths like `/workspace` and `/tmp`. Reading from system directories may be restricted for security.
</Note>

## Reading Text Files

Read text files as strings:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    # Write a file first
    sandbox.files.write('/workspace/data.txt', 'Hello, World!\nLine 2\nLine 3')

    # Read the file
    content = sandbox.files.read('/workspace/data.txt')
    print(content)
    # Output:
    # Hello, World!
    # Line 2
    # Line 3

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    Hello, World!
    Line 2
    Line 3
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Write a file first
    await sandbox.files.write('/workspace/data.txt', 'Hello, World!\nLine 2\nLine 3');

    // Read the file
    const content = await sandbox.files.read('/workspace/data.txt');
    console.log(content);
    // Output:
    // Hello, World!
    // Line 2
    // Line 3

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    Hello, World!
    Line 2
    Line 3
    ```
  </Tab>
</Tabs>

## Reading Binary Files

Read binary files (images, PDFs, etc.) as bytes:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    # Generate a plot and save it
    sandbox.run_code('''
    import matplotlib.pyplot as plt
    plt.plot([1, 2, 3, 4])
    plt.savefig('/workspace/plot.png')
    ''')

    # Read the binary image file
    image_data = sandbox.files.read_bytes('/workspace/plot.png')
    print(f"Image size: {len(image_data)} bytes")

    # Save to local file
    with open('local_plot.png', 'wb') as f:
        f.write(image_data)

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    Image size: 245760 bytes
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';
    import * as fs from 'fs';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Generate a plot and save it
    await sandbox.runCode(`
    import matplotlib.pyplot as plt
    plt.plot([1, 2, 3, 4])
    plt.savefig('/workspace/plot.png')
    `);

    // Read the binary image file
    const imageData = await sandbox.files.readBytes('/workspace/plot.png');
    console.log(`Image size: ${imageData.length} bytes`);

    // Save to local file
    fs.writeFileSync('local_plot.png', imageData);

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    Image size: 245760 bytes
    ```
  </Tab>
</Tabs>

## Reading Code Files

Read and execute code files:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    # Write a Python script
    sandbox.files.write('/workspace/script.py', '''
    def greet(name):
        return f"Hello, {name}!"

    print(greet("World"))
    ''')

    # Read and execute
    script_content = sandbox.files.read('/workspace/script.py')
    result = sandbox.run_code(script_content, language='python')
    print(result.stdout)  # "Hello, World!"

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    Hello, World!
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Write a Python script
    await sandbox.files.write('/workspace/script.py', `
    def greet(name):
        return f"Hello, {name}!"

    print(greet("World"))
    `);

    // Read and execute
    const scriptContent = await sandbox.files.read('/workspace/script.py');
    const result = await sandbox.runCode(scriptContent, { language: 'python' });
    console.log(result.stdout);  // "Hello, World!"

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    Hello, World!
    ```
  </Tab>
</Tabs>

## Reading Configuration Files

Read JSON, YAML, or other configuration files:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import json

    sandbox = Sandbox.create(template="code-interpreter")

    # Write a config file
    sandbox.files.write('/workspace/config.json', '''
    {
      "api_key": "sk-123",
      "debug": true,
      "timeout": 30
    }
    ''')

    # Read and parse
    config_content = sandbox.files.read('/workspace/config.json')
    config = json.loads(config_content)
    print(f"API key: {config['api_key']}")
    print(f"Debug: {config['debug']}")

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    API key: sk-123
    Debug: True
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Write a config file
    await sandbox.files.write('/workspace/config.json', `
    {
      "api_key": "sk-123",
      "debug": true,
      "timeout": 30
    }
    `);

    // Read and parse
    const configContent = await sandbox.files.read('/workspace/config.json');
    const config = JSON.parse(configContent);
    console.log(`API key: ${config.api_key}`);
    console.log(`Debug: ${config.debug}`);

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    API key: sk-123
    Debug: true
    ```
  </Tab>
</Tabs>

## Reading Large Files

For large files, consider using timeouts:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    # Read large file with custom timeout
    try:
        content = sandbox.files.read('/workspace/large_file.txt', timeout=120)
        print(f"Read {len(content)} characters")
    except Exception as e:
        print(f"Error reading file: {e}")

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    Read 1000000 characters
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Read large file (timeout handled by HTTP client)
    try {
      const content = await sandbox.files.read('/workspace/large_file.txt');
      console.log(`Read ${content.length} characters`);
    } catch (error) {
      console.error(`Error reading file: ${error.message}`);
    }

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    Read 1000000 characters
    ```
  </Tab>
</Tabs>

## Error Handling

Handle file reading errors:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    from hopx_ai.errors import FileNotFoundError, FileOperationError

    sandbox = Sandbox.create(template="code-interpreter")

    try:
        content = sandbox.files.read('/workspace/nonexistent.txt')
    except FileNotFoundError:
        print("File not found")
    except FileOperationError as e:
        print(f"File operation error: {e}")

    # Check if file exists first
    if sandbox.files.exists('/workspace/data.txt'):
        content = sandbox.files.read('/workspace/data.txt')
        print(content)
    else:
        print("File does not exist")

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    File not found
    File does not exist
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';
    import { FileNotFoundError, FileOperationError } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    try {
      const content = await sandbox.files.read('/workspace/nonexistent.txt');
    } catch (error) {
      if (error instanceof FileNotFoundError) {
        console.error('File not found');
      } else if (error instanceof FileOperationError) {
        console.error(`File operation error: ${error.message}`);
      }
    }

    // Check if file exists first
    const exists = await sandbox.files.exists('/workspace/data.txt');
    if (exists) {
      const content = await sandbox.files.read('/workspace/data.txt');
      console.log(content);
    } else {
      console.log('File does not exist');
    }

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    File not found
    File does not exist
    ```
  </Tab>
</Tabs>

## Reading Multiple Files

Read multiple files in a loop:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    # Create multiple files
    for i in range(3):
        sandbox.files.write(f'/workspace/file_{i}.txt', f'Content {i}')

    # Read all files
    files = sandbox.files.list('/workspace')
    for file in files:
        if file.is_file and file.name.endswith('.txt'):
            content = sandbox.files.read(file.path)
            print(f"{file.name}: {content}")

    sandbox.kill()
    ```

    **Expected Output:**

    ```
    file_0.txt: Content 0
    file_1.txt: Content 1
    file_2.txt: Content 2
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Create multiple files
    for (let i = 0; i < 3; i++) {
      await sandbox.files.write(`/workspace/file_${i}.txt`, `Content ${i}`);
    }

    // Read all files
    const files = await sandbox.files.list('/workspace');
    for (const file of files) {
      if (file.isFile && file.name.endsWith('.txt')) {
        const content = await sandbox.files.read(file.path);
        console.log(`${file.name}: ${content}`);
      }
    }

    await sandbox.kill();
    ```

    **Expected Output:**

    ```
    file_0.txt: Content 0
    file_1.txt: Content 1
    file_2.txt: Content 2
    ```
  </Tab>
</Tabs>

## Complete Example

Here's a complete example showing file reading workflow:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import json

    sandbox = Sandbox.create(template="code-interpreter")

    # Generate some files
    sandbox.run_code('''
    import json
    import matplotlib.pyplot as plt

    # Create data file
    data = {"values": [1, 2, 3, 4, 5]}
    with open('/workspace/data.json', 'w') as f:
        json.dump(data, f)

    # Create plot
    plt.plot([1, 2, 3, 4, 5])
    plt.savefig('/workspace/plot.png')

    # Create text file
    with open('/workspace/readme.txt', 'w') as f:
        f.write("Generated files:\n- data.json\n- plot.png")
    ''')

    # Read all generated files
    print("📄 Reading generated files:\n")

    # Read JSON data
    json_content = sandbox.files.read('/workspace/data.json')
    data = json.loads(json_content)
    print(f"Data: {data}")

    # Read binary plot
    plot_data = sandbox.files.read_bytes('/workspace/plot.png')
    print(f"Plot size: {len(plot_data)} bytes")

    # Read text file
    readme = sandbox.files.read('/workspace/readme.txt')
    print(f"\nReadme:\n{readme}")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({ template: 'code-interpreter' });

    // Generate some files
    await sandbox.runCode(`
    import json
    import matplotlib.pyplot as plt

    # Create data file
    data = {"values": [1, 2, 3, 4, 5]}
    with open('/workspace/data.json', 'w') as f:
        json.dump(data, f)

    # Create plot
    plt.plot([1, 2, 3, 4, 5])
    plt.savefig('/workspace/plot.png')

    # Create text file
    with open('/workspace/readme.txt', 'w') as f:
        f.write("Generated files:\\n- data.json\\n- plot.png")
    `);

    // Read all generated files
    console.log('📄 Reading generated files:\n');

    // Read JSON data
    const jsonContent = await sandbox.files.read('/workspace/data.json');
    const data = JSON.parse(jsonContent);
    console.log(`Data: ${JSON.stringify(data)}`);

    // Read binary plot
    const plotData = await sandbox.files.readBytes('/workspace/plot.png');
    console.log(`Plot size: ${plotData.length} bytes`);

    // Read text file
    const readme = await sandbox.files.read('/workspace/readme.txt');
    console.log(`\nReadme:\n${readme}`);

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="1. Check File Existence">
    Use `files.exists()` before reading to avoid errors, or handle `FileNotFoundError` appropriately.
  </Step>

  <Step title="2. Use Appropriate Method">
    Use `read()` for text files and `read_bytes()` for binary files (images, PDFs, etc.).
  </Step>

  <Step title="3. Set Timeouts for Large Files">
    For large files, set appropriate timeouts to avoid connection timeouts.
  </Step>

  <Step title="4. Handle Encoding">
    Text files are automatically decoded. Binary files return raw bytes.
  </Step>

  <Step title="5. Read from Allowed Paths">
    Only read from allowed paths like `/workspace` and `/tmp`. System directories may be restricted.
  </Step>
</Steps>

## Related

* **[Writing Files](/core-concepts/filesystem/writing)** - Write files to sandboxes
* **[Listing Files](/core-concepts/filesystem/listing)** - List directory contents
* **SDK**: [sandbox.files.read()](/sdk/python/files#read) - Python SDK method
* **API**: [GET /files/read](/api/vm-agent/read-file) - VM Agent API endpoint

## Next Steps

* Learn about [Writing Files](/core-concepts/filesystem/writing) to create files
* Explore [Listing Files](/core-concepts/filesystem/listing) to browse directories
* Review [Downloading Files](/core-concepts/filesystem/downloading) to save files locally