Skip to main content
See Filesystem for usage examples and extensible backends.

​
SandboxFs

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.

​
copy()

async def copy(src: str, dst: str) -> None
Copy a file within the sandbox. Parameters
NameTypeDescription
srcstrSource path
dststrDestination path

​
copy_from_host()

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
NameTypeDescription
host_pathstrPath on the host filesystem
guest_pathstrDestination path inside the sandbox

​
copy_to_host()

async def copy_to_host(guest_path: str, host_path: str) -> None
Copy a file from the sandbox to the host machine. Parameters
NameTypeDescription
guest_pathstrPath inside the sandbox
host_pathstrDestination path on the host

​
exists()

async def exists(path: str) -> bool
Check whether a path exists inside the sandbox. Parameters
NameTypeDescription
pathstrAbsolute path inside the guest
Returns
TypeDescription
boolTrue if the path exists

​
list()

async def list(path: str) -> list[FsEntry]
List the entries in a directory. Parameters
NameTypeDescription
pathstrAbsolute directory path inside the guest
Returns
TypeDescription
list[FsEntry]Directory entries

​
mkdir()

async def mkdir(path: str) -> None
Create a directory and all parent directories. Parameters
NameTypeDescription
pathstrAbsolute directory path

​
read()

async def read(path: str) -> bytes
Read the entire contents of a file as raw bytes. Parameters
NameTypeDescription
pathstrAbsolute path inside the guest (e.g. "/app/config.json")
Returns
TypeDescription
bytesFile contents as raw bytes

​
read_stream()

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
NameTypeDescription
pathstrAbsolute path inside the guest
Returns
TypeDescription
FsReadStreamAsync iterator that yields chunks of file data

​
read_text()

async def read_text(path: str) -> str
Read the entire contents of a file and decode as UTF-8. Parameters
NameTypeDescription
pathstrAbsolute path inside the guest
Returns
TypeDescription
strFile contents as a string

​
remove()

async def remove(path: str) -> None
Remove a file. Parameters
NameTypeDescription
pathstrAbsolute file path

​
remove_dir()

async def remove_dir(path: str) -> None
Remove a directory recursively. Parameters
NameTypeDescription
pathstrAbsolute directory path

​
rename()

async def rename(src: str, dst: str) -> None
Rename or move a file or directory within the sandbox. Parameters
NameTypeDescription
srcstrCurrent path
dststrNew path

​
stat()

async def stat(path: str) -> FsMetadata
Get detailed metadata for a file or directory. Parameters
NameTypeDescription
pathstrAbsolute path inside the guest
Returns
TypeDescription
FsMetadataFile metadata

​
write()

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
NameTypeDescription
pathstrAbsolute path inside the guest
databytesFile content

​
write_stream()

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
NameTypeDescription
pathstrAbsolute path inside the guest
Returns
TypeDescription
FsWriteSinkAsync writer that accepts chunks of data

​
Types

​
FsEntry

Metadata for a single directory entry, returned by list().
PropertyTypeDescription
kindstrType of entry ("file", "directory", "symlink", "other")
modeintUnix permission bits
modifiedfloat | NoneLast modified timestamp (ms since epoch)
pathstrFile path
sizeintFile size in bytes

​
FsEntryKind

String enum (StrEnum) representing the type of a filesystem entry.
ValueDescription
"directory"Directory
"file"Regular file
"other"Other entry type
"symlink"Symbolic link

​
FsMetadata

Detailed file metadata, returned by stat().
PropertyTypeDescription
createdfloat | NoneCreation timestamp (ms since epoch)
kindstrType of entry ("file", "directory", "symlink", "other")
modeintUnix permission bits
modifiedfloat | NoneLast modified timestamp (ms since epoch)
readonlyboolWhether the file is read-only
sizeintFile size in bytes

​
FsReadStream

Async stream for reading a file in chunks. Obtained via read_stream().
Method / ProtocolReturnsDescription
__aiter__ / __anext__bytesAsync iterator - use with async for chunk in stream:
collect()bytesCollect all remaining data into a single bytes object

​
FsWriteSink

Async writer for streaming data into a file. Obtained via write_stream(). Supports the async context manager protocol (async with).
Method / ProtocolReturnsDescription
write(data)NoneWrite a chunk of bytes to the file
close()NoneSend EOF and finalize the file
__aenter__ / __aexit__FsWriteSinkUse with async with for automatic close on exit