Skip to main content
Download files from sandboxes to your local filesystem. This is useful for retrieving generated outputs, results, plots, or any files created in your sandbox.

​
Overview

File downloading is essential for:
  • Retrieving generated outputs and results
  • Saving plots and visualizations
  • Downloading processed data files
  • Archiving sandbox contents
Download supports both text and binary files. Large files may take longer to download - set appropriate timeouts for large transfers.

​
Basic Download

Download a file from sandbox to local:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Create a file in sandbox
sandbox.files.write('/workspace/output.txt', 'Hello from sandbox!')

# Download to local filesystem
sandbox.files.download('/workspace/output.txt', './downloaded_output.txt')
print("File downloaded successfully")

# Verify download
with open('./downloaded_output.txt', 'r') as f:
    content = f.read()
    print(f"Downloaded content: {content}")

sandbox.kill()

​
Download with Timeout

Set timeout for large file downloads:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Generate a large file
sandbox.run_code('''
with open('/workspace/large_data.txt', 'w') as f:
    f.write('x' * 1000000)  # 1MB
''')

# Download with extended timeout
sandbox.files.download('/workspace/large_data.txt', './large_data.txt', timeout=300)
print("Large file downloaded")

# Verify
import os
file_size = os.path.getsize('./large_data.txt') / 1024 / 1024
print(f"Downloaded file size: {file_size:.2f} MB")

sandbox.kill()

​
Download Binary Files

Download binary files (images, PDFs, etc.):
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

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

# Download the image
sandbox.files.download('/workspace/plot.png', './local_plot.png')
print("Plot downloaded")

# Verify it's a valid image
with open('./local_plot.png', 'rb') as f:
    header = f.read(8)
    print(f"PNG header: {header[:8]}")  # Should start with PNG signature

sandbox.kill()

​
Download Multiple Files

Download multiple files:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import os

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

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

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

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

# Create text file
with open('/workspace/readme.txt', 'w') as f:
    f.write("Generated files")
''')

# Download all files
files_to_download = [
    ('/workspace/data.json', './downloaded_data.json'),
    ('/workspace/plot.png', './downloaded_plot.png'),
    ('/workspace/readme.txt', './downloaded_readme.txt')
]

print("📥 Downloading files...")
for remote_path, local_path in files_to_download:
    try:
        sandbox.files.download(remote_path, local_path)
        file_size = os.path.getsize(local_path) / 1024
        print(f"  ✅ {remote_path} → {local_path} ({file_size:.2f} KB)")
    except Exception as e:
        print(f"  ❌ Failed to download {remote_path}: {e}")

sandbox.kill()

​
Download All Files in Directory

Download all files from a directory:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import os

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}')

# Create local directory
os.makedirs('./downloads', exist_ok=True)

# Download all files
files = sandbox.files.list('/workspace')
print("📥 Downloading all files...")
for file in files:
    if file.is_file:
        local_path = f'./downloads/{file.name}'
        try:
            sandbox.files.download(file.path, local_path)
            print(f"  ✅ {file.name} ({file.size_kb:.2f} KB)")
        except Exception as e:
            print(f"  ❌ Failed to download {file.name}: {e}")

sandbox.kill()

​
Error Handling

Handle download errors:
  • Python
  • JavaScript
from hopx_ai import Sandbox
from hopx_ai.errors import FileNotFoundError, FileOperationError

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

try:
    # Try to download non-existent file
    sandbox.files.download('/workspace/nonexistent.txt', './downloaded.txt')
except FileNotFoundError:
    print("File not found in sandbox")
except FileOperationError as e:
    print(f"Download failed: {e}")

# Check if file exists first
if sandbox.files.exists('/workspace/data.txt'):
    sandbox.files.download('/workspace/data.txt', './data.txt')
    print("Download successful")
else:
    print("File does not exist")

sandbox.kill()

​
Complete Example

Here’s a complete download workflow:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import os

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

# Generate outputs
sandbox.run_code('''
import json
import matplotlib.pyplot as plt
import pandas as pd

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

# Generate plot
plt.figure(figsize=(10, 6))
plt.plot([1, 2, 3, 4, 5], [1, 4, 9, 16, 25])
plt.title("Results Visualization")
plt.savefig('/workspace/results.png')

# Generate CSV
df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
df.to_csv('/workspace/data.csv', index=False)
''')

# Create local output directory
os.makedirs('./outputs', exist_ok=True)

# Download all generated files
print("📥 Downloading generated outputs...")
files = sandbox.files.list('/workspace')
total_size = 0

for file in files:
    if file.is_file and file.name in ['results.json', 'results.png', 'data.csv']:
        local_path = f'./outputs/{file.name}'
        try:
            sandbox.files.download(file.path, local_path, timeout=120)
            total_size += file.size
            print(f"  ✅ {file.name} ({file.size_kb:.2f} KB)")
        except Exception as e:
            print(f"  ❌ Failed to download {file.name}: {e}")

print(f"\n✅ Total downloaded: {total_size / 1024:.2f} KB")
print(f"📁 Files saved to: ./outputs/")

sandbox.kill()

​
Best Practices

1

1. Check File Existence

Use files.exists() before downloading to avoid errors, or handle FileNotFoundError appropriately.
2

2. Set Timeouts for Large Files

For large files, set extended timeouts (60+ seconds) to avoid connection timeouts.
3

3. Create Local Directories

Create local directories before downloading to ensure files are saved correctly.
4

4. Handle Errors Gracefully

Wrap downloads in try/catch blocks to handle network errors, file not found, etc.
5

5. Verify Downloads

After downloading, verify files exist locally and check their sizes to ensure successful transfer.

​
Next Steps