Downloading

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()

import { Sandbox } from '@hopx-ai/sdk';
import * as fs from 'fs';

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

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

// Download to local filesystem
const content = await sandbox.files.download('/workspace/output.txt');
fs.writeFileSync('./downloaded_output.txt', content);
console.log('File downloaded successfully');

// Verify download
const downloadedContent = fs.readFileSync('./downloaded_output.txt', 'utf-8');
console.log(`Downloaded content: ${downloadedContent}`);

await 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()

import { Sandbox } from '@hopx-ai/sdk';
import * as fs from 'fs';

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

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

// Download
const content = await sandbox.files.download('/workspace/large_data.txt');
fs.writeFileSync('./large_data.txt', content);
console.log('Large file downloaded');

// Verify
const stats = fs.statSync('./large_data.txt');
const fileSize = stats.size / 1024 / 1024;
console.log(`Downloaded file size: ${fileSize.toFixed(2)} MB`);

await 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()

import { Sandbox } from '@hopx-ai/sdk';
import * as fs from 'fs';

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

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

// Download the image
const imageData = await sandbox.files.download('/workspace/plot.png');
fs.writeFileSync('./local_plot.png', imageData);
console.log('Plot downloaded');

// Verify it's a valid image
const buffer = fs.readFileSync('./local_plot.png');
console.log(`PNG header: ${buffer.slice(0, 8)}`);  // Should start with PNG signature

await 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()

import { Sandbox } from '@hopx-ai/sdk';
import * as fs from 'fs';

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

// Generate multiple files
await sandbox.runCode(`
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
const filesToDownload = [
  ['/workspace/data.json', './downloaded_data.json'],
  ['/workspace/plot.png', './downloaded_plot.png'],
  ['/workspace/readme.txt', './downloaded_readme.txt']
];

console.log('📥 Downloading files...');
for (const [remotePath, localPath] of filesToDownload) {
  try {
    const content = await sandbox.files.download(remotePath);
    fs.writeFileSync(localPath, content);
    const stats = fs.statSync(localPath);
    const fileSize = stats.size / 1024;
    console.log(`  ✅ ${remotePath} → ${localPath} (${fileSize.toFixed(2)} KB)`);
  } catch (error) {
    console.error(`  ❌ Failed to download ${remotePath}: ${error.message}`);
  }
}

await 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()

import { Sandbox } from '@hopx-ai/sdk';
import * as fs from 'fs';
import * as path from 'path';

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}`);
}

// Create local directory
if (!fs.existsSync('./downloads')) {
  fs.mkdirSync('./downloads');
}

// Download all files
const files = await sandbox.files.list('/workspace');
console.log('📥 Downloading all files...');
for (const file of files) {
  if (file.isFile) {
    const localPath = `./downloads/${file.name}`;
    try {
      const content = await sandbox.files.download(file.path);
      fs.writeFileSync(localPath, content);
      console.log(`  ✅ ${file.name} (${(file.size / 1024).toFixed(2)} KB)`);
    } catch (error) {
      console.error(`  ❌ Failed to download ${file.name}: ${error.message}`);
    }
  }
}

await 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()

import { Sandbox } from '@hopx-ai/sdk';
import { FileNotFoundError, FileOperationError } from '@hopx-ai/sdk';

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

try {
  // Try to download non-existent file
  await sandbox.files.download('/workspace/nonexistent.txt');
} catch (error) {
  if (error instanceof FileNotFoundError) {
    console.error('File not found in sandbox');
  } else if (error instanceof FileOperationError) {
    console.error(`Download failed: ${error.message}`);
  }
}

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

await 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()

import { Sandbox } from '@hopx-ai/sdk';
import * as fs from 'fs';

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

// Generate outputs
await sandbox.runCode(`
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
if (!fs.existsSync('./outputs')) {
  fs.mkdirSync('./outputs');
}

// Download all generated files
console.log('📥 Downloading generated outputs...');
const files = await sandbox.files.list('/workspace');
let totalSize = 0;

for (const file of files) {
  if (file.isFile && ['results.json', 'results.png', 'data.csv'].includes(file.name)) {
    const localPath = `./outputs/${file.name}`;
    try {
      const content = await sandbox.files.download(file.path);
      fs.writeFileSync(localPath, content);
      totalSize += file.size;
      console.log(`  ✅ ${file.name} (${(file.size / 1024).toFixed(2)} KB)`);
    } catch (error) {
      console.error(`  ❌ Failed to download ${file.name}: ${error.message}`);
    }
  }
}

console.log(`\n✅ Total downloaded: ${(totalSize / 1024).toFixed(2)} KB`);
console.log('📁 Files saved to: ./outputs/');

await sandbox.kill();

Best Practices

1. Check File Existence

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

2. Set Timeouts for Large Files

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

3. Create Local Directories

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

4. Handle Errors Gracefully

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

5. Verify Downloads

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

Reading Files - Read file contents
Uploading Files - Upload files to sandboxes
Listing Files - List directory contents
SDK: sandbox.files.download() - Python SDK method
CLI File Operations - File operations from CLI

Next Steps

Learn about Uploading Files to transfer files to sandboxes
Explore Reading Files to access file contents
Review Watching Files for real-time file monitoring

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Basic Download

Download with Timeout

Download Binary Files

Download Multiple Files

Download All Files in Directory

Error Handling

Complete Example

Best Practices

Next Steps

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Documentation Index

​Overview

​Basic Download

​Download with Timeout

​Download Binary Files

​Download Multiple Files

​Download All Files in Directory

​Error Handling

​Complete Example

​Best Practices

​Related

​Next Steps

Overview

Basic Download

Download with Timeout

Download Binary Files

Download Multiple Files

Download All Files in Directory

Error Handling

Complete Example

Best Practices

Related

Next Steps