Skip to main content
The Files resource provides comprehensive file system operations for working with files and directories inside sandboxes.

​
Accessing Files Resource

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

const sandbox = await Sandbox.create({ template: 'code-interpreter' });
await sandbox.init();
const files = sandbox.files;  // Lazy-loaded resource

​
Reading Files

​
read()

Read text file contents. 
const content = await sandbox.files.read('/workspace/data.txt');
console.log(content);
Method Signature: 
async read(path: string): Promise<string>
Example: 
// Read configuration file
const config = await sandbox.files.read('/workspace/config.json');

// Read Python script
const script = await sandbox.files.read('/workspace/main.py');

​
readBytes()

Read binary file contents. 
const imageData = await sandbox.files.readBytes('/workspace/plot.png');
await fs.promises.writeFile('local_plot.png', imageData);
Method Signature: 
async readBytes(path: string): Promise<Buffer>
Use Cases:
  • Images (PNG, JPG, etc.)
  • PDFs
  • Binary data files
  • Compressed archives

​
Writing Files

​
write()

Write text file contents. 
await sandbox.files.write('/workspace/hello.py', 'print("Hello, World!")');
Method Signature: 
async write(
  path: string,
  content: string,
  options?: FileWriteOptions
): Promise<void>
Options: 
interface FileWriteOptions {
  overwrite?: boolean;  // Overwrite if exists (default: true)
}

​
writeBytes()

Write binary file contents. 
const imageData = await fs.promises.readFile('image.png');
await sandbox.files.writeBytes('/workspace/image.png', imageData);
Method Signature: 
async writeBytes(
  path: string,
  content: Buffer,
  options?: FileWriteOptions
): Promise<void>

​
Directory Operations

​
list()

List directory contents. 
const files = await sandbox.files.list('/workspace');
for (const f of files) {
  if (f.isFile) {
    console.log(`📄 ${f.name}: ${f.sizeKb.toFixed(2)} KB`);
  } else {
    console.log(`📁 ${f.name}/`);
  }
}
Method Signature: 
async list(path: string): Promise<FileInfo[]>
FileInfo Properties:
  • name (string): File/directory name
  • path (string): Full path
  • size (number): Size in bytes
  • sizeKb (number): Size in KB
  • isFile (boolean): True if file
  • isDirectory (boolean): True if directory
  • permissions (string): File permissions
  • modifiedTime (string): Last modified time

​
mkdir()

Create directory. 
await sandbox.files.mkdir('/workspace/data');
await sandbox.files.mkdir('/workspace/project/src');  // Creates nested
Method Signature: 
async mkdir(path: string): Promise<void>

​
exists()

Check if file or directory exists. 
if (await sandbox.files.exists('/workspace/data.csv')) {
  console.log('File exists!');
  const content = await sandbox.files.read('/workspace/data.csv');
} else {
  console.log('File not found');
}
Method Signature: 
async exists(path: string): Promise<boolean>

​
remove()

Delete file or directory. 
// Remove file
await sandbox.files.remove('/workspace/temp.txt');

// Remove directory (recursive)
await sandbox.files.remove('/workspace/old_data');
Method Signature: 
async remove(path: string): Promise<void>

​
File Transfer

​
download()

Download file from sandbox to local filesystem. 
const fileData = await sandbox.files.download('/workspace/result.csv');
await fs.promises.writeFile('./result.csv', fileData);
Method Signature: 
async download(path: string): Promise<Buffer>

​
Examples

​
Working with CSV Files

// Write CSV
const csvData = 'name,age\nAlice,30\nBob,25';
await sandbox.files.write('/workspace/data.csv', csvData);

// Read CSV
const content = await sandbox.files.read('/workspace/data.csv');

// Process with pandas
const result = await sandbox.runCode(
  `
import pandas as pd
df = pd.read_csv('/workspace/data.csv')
print(df.describe())
`
);

// Download result
const resultData = await sandbox.files.download('/workspace/result.csv');
await fs.promises.writeFile('./result.csv', resultData);