> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# File System Operations

> Upload, download, and manage files within your sandbox environment

Each sandbox has a built-in file system API available at `sb.fs`. You can upload local files, download files from the sandbox, list directories, and manage files with full metadata access.

## Uploading Files

### Basic File Upload

```python theme={null}
from beam import Sandbox, Image, PythonVersion

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

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
# 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}")
```

## File Management

### Listing Files and Directories

```python theme={null}
# 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)")
```

### File Information

```python theme={null}
# 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}")
```