docs/sdk/python/filesystem.mdx
See Filesystem for usage examples and extensible backends.
Filesystem handle for a running sandbox. Obtained via the sandbox.fs property. All operations go through the same host-guest channel as command execution - no SSH, no network involved. For bulk file operations, consider using volumes instead.
async def copy(src: str, dst: str) -> None
Copy a file within the sandbox.
Parameters
| Name | Type | Description |
|---|---|---|
| src | str | Source path |
| dst | str | Destination path |
async def copy_from_host(host_path: str, guest_path: str) -> None
Copy a file from the host machine into the sandbox. For transferring many files, consider a bind-mounted volume instead.
Parameters
| Name | Type | Description |
|---|---|---|
| host_path | str | Path on the host filesystem |
| guest_path | str | Destination path inside the sandbox |
async def copy_to_host(guest_path: str, host_path: str) -> None
Copy a file from the sandbox to the host machine.
Parameters
| Name | Type | Description |
|---|---|---|
| guest_path | str | Path inside the sandbox |
| host_path | str | Destination path on the host |
async def exists(path: str) -> bool
Check whether a path exists inside the sandbox.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest |
Returns
| Type | Description |
|---|---|
bool | True if the path exists |
async def list(path: str) -> list[FsEntry]
List the entries in a directory.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute directory path inside the guest |
Returns
| Type | Description |
|---|---|
list[FsEntry] | Directory entries |
async def mkdir(path: str) -> None
Create a directory and all parent directories.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute directory path |
async def read(path: str) -> bytes
Read the entire contents of a file as raw bytes.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest (e.g. "/app/config.json") |
Returns
| Type | Description |
|---|---|
bytes | File contents as raw bytes |
async def read_stream(path: str) -> FsReadStream
Open a streaming reader for a file. Data is transferred in chunks of approximately 3 MiB each. Use this for files too large to fit in memory.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest |
Returns
| Type | Description |
|---|---|
FsReadStream | Async iterator that yields chunks of file data |
async def read_text(path: str) -> str
Read the entire contents of a file and decode as UTF-8.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest |
Returns
| Type | Description |
|---|---|
str | File contents as a string |
async def remove(path: str) -> None
Remove a file.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute file path |
async def remove_dir(path: str) -> None
Remove a directory recursively.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute directory path |
async def rename(src: str, dst: str) -> None
Rename or move a file or directory within the sandbox.
Parameters
| Name | Type | Description |
|---|---|---|
| src | str | Current path |
| dst | str | New path |
async def stat(path: str) -> FsMetadata
Get detailed metadata for a file or directory.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest |
Returns
| Type | Description |
|---|---|
FsMetadata | File metadata |
async def write(path: str, data: bytes) -> None
Write content to a file, creating it if it doesn't exist and overwriting if it does.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest |
| data | bytes | File content |
async def write_stream(path: str) -> FsWriteSink
Open a streaming writer for a file. Use this for files too large to fit in memory.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | Absolute path inside the guest |
Returns
| Type | Description |
|---|---|
FsWriteSink | Async writer that accepts chunks of data |
Metadata for a single directory entry, returned by list().
| Property | Type | Description |
|---|---|---|
| kind | str | Type of entry ("file", "directory", "symlink", "other") |
| mode | int | Unix permission bits |
| modified | float | None | Last modified timestamp (ms since epoch) |
| path | str | File path |
| size | int | File size in bytes |
String enum (StrEnum) representing the type of a filesystem entry.
| Value | Description |
|---|---|
"directory" | Directory |
"file" | Regular file |
"other" | Other entry type |
"symlink" | Symbolic link |
Detailed file metadata, returned by stat().
| Property | Type | Description |
|---|---|---|
| created | float | None | Creation timestamp (ms since epoch) |
| kind | str | Type of entry ("file", "directory", "symlink", "other") |
| mode | int | Unix permission bits |
| modified | float | None | Last modified timestamp (ms since epoch) |
| readonly | bool | Whether the file is read-only |
| size | int | File size in bytes |
Async stream for reading a file in chunks. Obtained via read_stream().
| Method / Protocol | Returns | Description |
|---|---|---|
__aiter__ / __anext__ | bytes | Async iterator - use with async for chunk in stream: |
collect() | bytes | Collect all remaining data into a single bytes object |
Async writer for streaming data into a file. Obtained via write_stream(). Supports the async context manager protocol (async with).
| Method / Protocol | Returns | Description |
|---|---|---|
write(data) | None | Write a chunk of bytes to the file |
close() | None | Send EOF and finalize the file |
__aenter__ / __aexit__ | FsWriteSink | Use with async with for automatic close on exit |