The Sandbox provides a file system interface through the fs property. You can upload local files, download files from the sandbox, list directories, and manage files with full metadata access.

​
Uploading Files

​
Basic File Upload

from beam import Sandbox, Image

sandbox = Sandbox(image=Image(python_version=PythonVersion.Python311))
sb = sandbox.create()

# Upload a local file to the sandbox
sb.fs.upload_file("my_script.py", "/workspace/my_script.py")

​
Uploading Multiple Files

# Upload several files
files_to_upload = [
    ("main.py", "/workspace/main.py"),
    ("requirements.txt", "/workspace/requirements.txt"),
    ("data.csv", "/workspace/data/data.csv"),
    ("config.yaml", "/workspace/config/config.yaml")
]

for local_path, sandbox_path in files_to_upload:
    sb.fs.upload_file(local_path, sandbox_path)
    print(f"Uploaded {local_path} to {sandbox_path}")

​
Downloading Files

​
Basic File Download

# Download a file from the sandbox
sb.fs.download_file("/workspace/output.txt", "local_output.txt")

# Download to a specific directory
sb.fs.download_file("/workspace/results/data.csv", "downloads/data.csv")

​
Downloading Multiple Files

# Download all files in a directory
files = sb.fs.list_files("/workspace/results")
for file in files:
    if not file.is_dir:
        local_path = f"downloads/{file.name}"
        sb.fs.download_file(f"/workspace/results/{file.name}", local_path)
        print(f"Downloaded {file.name}")

​
Downloading with Progress

import os

def download_with_progress(sandbox_path, local_path):
    # Get file info first
    file_info = sb.fs.stat_file(sandbox_path)
    print(f"Downloading {file_info.name} ({file_info.size} bytes)...")
    
    # Download the file
    sb.fs.download_file(sandbox_path, local_path)
    
    # Verify download
    if os.path.exists(local_path):
        local_size = os.path.getsize(local_path)
        if local_size == file_info.size:
            print(f"Successfully downloaded {file_info.name}")
        else:
            print(f"Warning: Size mismatch for {file_info.name}")
    else:
        print(f"Error: Failed to download {file_info.name}")

download_with_progress("/workspace/large_file.dat", "local_large_file.dat")

​
File Management

​
Listing Files and Directories

# List files in workspace
files = sb.fs.list_files("/workspace")
for file in files:
    if file.is_dir:
        print(f"📁 {file.name}/")
    else:
        print(f"📄 {file.name} ({file.size} bytes)")

​
Recursive Directory Listing

def list_directory_recursive(path, indent=0):
    files = sb.fs.list_files(path)
    
    for file in files:
        prefix = "  " * indent
        if file.is_dir:
            print(f"{prefix}📁 {file.name}/")
            list_directory_recursive(f"{path}/{file.name}", indent + 1)
        else:
            print(f"{prefix}📄 {file.name} ({file.size} bytes)")

# List entire workspace structure
list_directory_recursive("/workspace")

​
File Information

# Get detailed information about a file
file_info = sb.fs.stat_file("/workspace/my_script.py")

print(f"Name: {file_info.name}")
print(f"Size: {file_info.size} bytes")
print(f"Is Directory: {file_info.is_dir}")
print(f"Permissions: {oct(file_info.permissions)}")
print(f"Owner: {file_info.owner}")
print(f"Group: {file_info.group}")
print(f"Modified: {file_info.mod_time}")