Listing

List directory contents to browse your sandbox filesystem. Get file metadata including size, permissions, and modification times.

Overview

Directory listing is useful for:

Browsing sandbox filesystem structure
Finding files by name or pattern
Checking file sizes and metadata
Discovering generated outputs

You can list contents of allowed paths like /workspace and /tmp. Listing system directories may be restricted for security.

Basic Listing

List files in a directory:

Python
JavaScript

from hopx_ai import Sandbox

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

# Create some files
sandbox.files.write('/workspace/file1.txt', 'Content 1')
sandbox.files.write('/workspace/file2.txt', 'Content 2')
sandbox.files.mkdir('/workspace/subdir')

# List directory contents
files = sandbox.files.list('/workspace')
print(f"Found {len(files)} items")

for file in files:
    if file.is_file:
        print(f"📄 {file.name} ({file.size_kb:.2f} KB)")
    else:
        print(f"📁 {file.name}/")

sandbox.kill()

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

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

// Create some files
await sandbox.files.write('/workspace/file1.txt', 'Content 1');
await sandbox.files.write('/workspace/file2.txt', 'Content 2');
await sandbox.files.mkdir('/workspace/subdir');

// List directory contents
const files = await sandbox.files.list('/workspace');
console.log(`Found ${files.length} items`);

for (const file of files) {
  if (file.isFile) {
    console.log(`📄 ${file.name} (${(file.size / 1024).toFixed(2)} KB)`);
  } else {
    console.log(`📁 ${file.name}/`);
  }
}

await sandbox.kill();

File Information

Access detailed file information:

Python
JavaScript

from hopx_ai import Sandbox

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

# Create a file
sandbox.files.write('/workspace/data.txt', 'Some content')

# List and get file info
files = sandbox.files.list('/workspace')
for file in files:
    if file.name == 'data.txt':
        print(f"Name: {file.name}")
        print(f"Path: {file.path}")
        print(f"Size: {file.size} bytes")
        print(f"Size (KB): {file.size_kb:.2f} KB")
        print(f"Size (MB): {file.size_mb:.2f} MB")
        print(f"Is file: {file.is_file}")
        print(f"Is directory: {file.is_dir}")
        print(f"Permissions: {file.permissions}")
        print(f"Modified: {file.modified_time}")

sandbox.kill()

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

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

// Create a file
await sandbox.files.write('/workspace/data.txt', 'Some content');

// List and get file info
const files = await sandbox.files.list('/workspace');
for (const file of files) {
  if (file.name === 'data.txt') {
    console.log(`Name: ${file.name}`);
    console.log(`Path: ${file.path}`);
    console.log(`Size: ${file.size} bytes`);
    console.log(`Size (KB): ${(file.size / 1024).toFixed(2)} KB`);
    console.log(`Size (MB): ${(file.size / 1024 / 1024).toFixed(2)} MB`);
    console.log(`Is file: ${file.isFile}`);
    console.log(`Is directory: ${file.isDirectory}`);
    console.log(`Permissions: ${file.permissions}`);
    console.log(`Modified: ${file.modifiedTime}`);
  }
}

await sandbox.kill();

Filtering Files

Filter files by type or pattern:

Python
JavaScript

from hopx_ai import Sandbox

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

# Create various files
sandbox.files.write('/workspace/script.py', 'print("Hello")')
sandbox.files.write('/workspace/data.json', '{"key": "value"}')
sandbox.files.write('/workspace/readme.txt', 'Documentation')

# List only Python files
files = sandbox.files.list('/workspace')
python_files = [f for f in files if f.is_file and f.name.endswith('.py')]
print(f"Python files: {len(python_files)}")
for f in python_files:
    print(f"  {f.name}")

# List only directories
directories = [f for f in files if f.is_dir]
print(f"\nDirectories: {len(directories)}")
for d in directories:
    print(f"  {d.name}/")

sandbox.kill()

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

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

// Create various files
await sandbox.files.write('/workspace/script.py', 'print("Hello")');
await sandbox.files.write('/workspace/data.json', '{"key": "value"}');
await sandbox.files.write('/workspace/readme.txt', 'Documentation');

// List only Python files
const files = await sandbox.files.list('/workspace');
const pythonFiles = files.filter(f => f.isFile && f.name.endsWith('.py'));
console.log(`Python files: ${pythonFiles.length}`);
for (const f of pythonFiles) {
  console.log(`  ${f.name}`);
}

// List only directories
const directories = files.filter(f => f.isDirectory);
console.log(`\nDirectories: ${directories.length}`);
for (const d of directories) {
  console.log(`  ${d.name}/`);
}

await sandbox.kill();

Recursive Listing

List files recursively by traversing directories:

Python
JavaScript

from hopx_ai import Sandbox

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

# Create nested structure
sandbox.files.mkdir('/workspace/project')
sandbox.files.mkdir('/workspace/project/src')
sandbox.files.write('/workspace/project/src/main.py', 'print("Hello")')
sandbox.files.write('/workspace/project/README.md', '# Project')

def list_recursive(files, path='/workspace', indent=0):
    """Recursively list directory contents"""
    items = sandbox.files.list(path)
    for item in items:
        prefix = "  " * indent
        if item.is_dir:
            print(f"{prefix}📁 {item.name}/")
            list_recursive(files, item.path, indent + 1)
        else:
            print(f"{prefix}📄 {item.name} ({item.size_kb:.2f} KB)")

print("Directory structure:")
list_recursive(sandbox.files.list('/workspace'))

sandbox.kill()

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

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

// Create nested structure
await sandbox.files.mkdir('/workspace/project');
await sandbox.files.mkdir('/workspace/project/src');
await sandbox.files.write('/workspace/project/src/main.py', 'print("Hello")');
await sandbox.files.write('/workspace/project/README.md', '# Project');

async function listRecursive(path = '/workspace', indent = 0) {
  const items = await sandbox.files.list(path);
  for (const item of items) {
    const prefix = '  '.repeat(indent);
    if (item.isDirectory) {
      console.log(`${prefix}📁 ${item.name}/`);
      await listRecursive(item.path, indent + 1);
    } else {
      console.log(`${prefix}📄 ${item.name} (${(item.size / 1024).toFixed(2)} KB)`);
    }
  }
}

console.log('Directory structure:');
await listRecursive('/workspace');

await sandbox.kill();

Sorting and Filtering

Sort files by size, name, or date:

Python
JavaScript

from hopx_ai import Sandbox

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

# Create files of different sizes
sandbox.files.write('/workspace/small.txt', 'small')
sandbox.files.write('/workspace/medium.txt', 'x' * 1000)
sandbox.files.write('/workspace/large.txt', 'x' * 10000)

# List and sort by size
files = sandbox.files.list('/workspace')
files_only = [f for f in files if f.is_file]

# Sort by size (largest first)
sorted_by_size = sorted(files_only, key=lambda f: f.size, reverse=True)
print("Files sorted by size:")
for f in sorted_by_size:
    print(f"  {f.name}: {f.size_kb:.2f} KB")

# Sort by name
sorted_by_name = sorted(files_only, key=lambda f: f.name)
print("\nFiles sorted by name:")
for f in sorted_by_name:
    print(f"  {f.name}")

sandbox.kill()

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

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

// Create files of different sizes
await sandbox.files.write('/workspace/small.txt', 'small');
await sandbox.files.write('/workspace/medium.txt', 'x'.repeat(1000));
await sandbox.files.write('/workspace/large.txt', 'x'.repeat(10000));

// List and sort by size
const files = await sandbox.files.list('/workspace');
const filesOnly = files.filter(f => f.isFile);

// Sort by size (largest first)
const sortedBySize = filesOnly.sort((a, b) => b.size - a.size);
console.log('Files sorted by size:');
for (const f of sortedBySize) {
  console.log(`  ${f.name}: ${(f.size / 1024).toFixed(2)} KB`);
}

// Sort by name
const sortedByName = filesOnly.sort((a, b) => a.name.localeCompare(b.name));
console.log('\nFiles sorted by name:');
for (const f of sortedByName) {
  console.log(`  ${f.name}`);
}

await sandbox.kill();

Complete Example

Here’s a complete example showing directory listing:

Python
JavaScript

from hopx_ai import Sandbox

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

# Create a project structure
sandbox.files.mkdir('/workspace/myproject')
sandbox.files.mkdir('/workspace/myproject/src')
sandbox.files.mkdir('/workspace/myproject/tests')
sandbox.files.mkdir('/workspace/myproject/data')

# Create files
sandbox.files.write('/workspace/myproject/src/main.py', 'print("Hello")')
sandbox.files.write('/workspace/myproject/src/utils.py', 'def helper(): pass')
sandbox.files.write('/workspace/myproject/tests/test_main.py', 'def test(): pass')
sandbox.files.write('/workspace/myproject/data/input.csv', '1,2,3')
sandbox.files.write('/workspace/myproject/README.md', '# My Project')

# List and display structure
def display_tree(path, prefix=""):
    files = sandbox.files.list(path)
    files.sort(key=lambda f: (f.is_dir, f.name))
    
    for i, file in enumerate(files):
        is_last = i == len(files) - 1
        current_prefix = "└── " if is_last else "├── "
        print(f"{prefix}{current_prefix}{file.name}")
        
        if file.is_dir:
            next_prefix = prefix + ("    " if is_last else "│   ")
            display_tree(file.path, next_prefix)

print("Project structure:")
display_tree('/workspace/myproject')

# Summary
all_files = sandbox.files.list('/workspace/myproject')
total_size = sum(f.size for f in all_files if f.is_file)
print(f"\nTotal files: {len([f for f in all_files if f.is_file])}")
print(f"Total size: {total_size / 1024:.2f} KB")

sandbox.kill()

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

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

// Create a project structure
await sandbox.files.mkdir('/workspace/myproject');
await sandbox.files.mkdir('/workspace/myproject/src');
await sandbox.files.mkdir('/workspace/myproject/tests');
await sandbox.files.mkdir('/workspace/myproject/data');

// Create files
await sandbox.files.write('/workspace/myproject/src/main.py', 'print("Hello")');
await sandbox.files.write('/workspace/myproject/src/utils.py', 'def helper(): pass');
await sandbox.files.write('/workspace/myproject/tests/test_main.py', 'def test(): pass');
await sandbox.files.write('/workspace/myproject/data/input.csv', '1,2,3');
await sandbox.files.write('/workspace/myproject/README.md', '# My Project');

// List and display structure
async function displayTree(path, prefix = '') {
  const files = await sandbox.files.list(path);
  files.sort((a, b) => {
    if (a.isDirectory !== b.isDirectory) {
      return a.isDirectory ? -1 : 1;
    }
    return a.name.localeCompare(b.name);
  });
  
  for (let i = 0; i < files.length; i++) {
    const file = files[i];
    const isLast = i === files.length - 1;
    const currentPrefix = isLast ? '└── ' : '├── ';
    console.log(`${prefix}${currentPrefix}${file.name}`);
    
    if (file.isDirectory) {
      const nextPrefix = prefix + (isLast ? '    ' : '│   ');
      await displayTree(file.path, nextPrefix);
    }
  }
}

console.log('Project structure:');
await displayTree('/workspace/myproject');

// Summary
const allFiles = await sandbox.files.list('/workspace/myproject');
const totalSize = allFiles.filter(f => f.isFile).reduce((sum, f) => sum + f.size, 0);
console.log(`\nTotal files: ${allFiles.filter(f => f.isFile).length}`);
console.log(`Total size: ${(totalSize / 1024).toFixed(2)} KB`);

await sandbox.kill();

Best Practices

1. Check Directory Existence

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

2. Filter by Type

Use is_file and is_dir properties to filter files and directories.

3. Sort for Display

Sort files by name, size, or date for better user experience.

4. Use Recursive Listing

For nested structures, implement recursive listing to show complete directory trees.

5. Handle Large Directories

For directories with many files, consider pagination or filtering to avoid performance issues.

Reading Files - Read file contents
Writing Files - Write files to sandboxes
SDK: sandbox.files.list() - Python SDK method
API: GET /files/list - VM Agent API endpoint
CLI File Operations - File operations from CLI

Next Steps

Learn about Reading Files to access file contents
Explore Writing Files to create files
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 Listing

File Information

Filtering Files

Recursive Listing

Sorting and Filtering

Complete Example

Best Practices

Next Steps

​Overview

​Basic Listing

​File Information

​Filtering Files

​Recursive Listing

​Sorting and Filtering

​Complete Example

​Best Practices

​Related

​Next Steps

Overview

Basic Listing

File Information

Filtering Files

Recursive Listing

Sorting and Filtering

Complete Example

Best Practices

Related

Next Steps