> ## 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

> Read and write files, transfer data, inspect metadata, and search sandbox files

Use `sb.fs` on a running sandbox. Sandbox-local files disappear when the sandbox ends unless you capture a filesystem image or write to mounted persistent storage.

## Read and write without local temporary files

```python theme={null}
sb.fs.write_text("/workspace/config.json", '{"debug": false}')
print(sb.fs.read_text("/workspace/config.json"))

sb.fs.write_bytes("/workspace/input.bin", b"example")
data = sb.fs.read_bytes("/workspace/input.bin")
```

`write_text` accepts `encoding` (default UTF-8) and `mode`; `write_bytes` accepts `mode`. Both default to file permissions `0o644`.

## Transfer local files

```python theme={null}
sb.fs.upload_file("input.csv", "/workspace/input.csv")
sb.fs.download_file("/workspace/output.csv", "output.csv")
```

Create destination directories with `sb.fs.create_directory("/workspace/results")` when your workflow needs them. Use volumes or cloud buckets for shared datasets; see [storage configuration](/v2/sandbox/configuration#persistent-storage).

## Inspect and wait

```python theme={null}
for info in sb.fs.list_files("/workspace"):
    print(info.name, info.size, info.is_dir)

info = sb.fs.stat_file("/workspace/config.json")
print(info.name, info.size, info.mod_time)

# Wait for a producer to create a file; optionally require an exact byte size.
sb.fs.wait_for("/workspace/result.json", timeout=60)
```

`wait_for` checks for the file; it does not wait for a process to exit. When possible, wait for the producing process first so you know the write completed.

## Search, replace, and remove

```python theme={null}
matches = sb.fs.find_in_files("/workspace", "TODO")
print(matches)

sb.fs.replace_in_files("/workspace/config.json", '"debug": false', '"debug": true')
# Literal replacement is the default. Pass regex=True for a regular expression.

sb.fs.delete_file("/workspace/input.bin")
sb.fs.delete_directory("/workspace/results")
# remove() chooses file or directory removal automatically.
sb.fs.remove("/workspace/config.json")
```

`find_in_files` searches file contents using the supplied pattern; it is not a filename glob search. Methods raise `SandboxFileSystemError` when a filesystem operation fails.

## Async operations

The same operations are available through `sb.aio.fs`:

```python theme={null}
async def write_and_read(sb):
    await sb.aio.fs.write_text("/workspace/message.txt", "hello")
    return await sb.aio.fs.read_text("/workspace/message.txt")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.