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

​
SandboxFs

Filesystem handle for a running sandbox. Obtained via sb.fs(). 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, which give the guest direct filesystem access.

​
copy()

async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()>
Copy a file within the sandbox. Parameters
NameTypeDescription
from&strSource path
to&strDestination path

​
copy_from_host()

async fn copy_from_host(&self, host_path: impl AsRef<Path>, guest_path: &str) -> MicrosandboxResult<()>
Copy a file from the host machine into the sandbox. For transferring many files, consider a bind-mounted volume instead. Parameters
NameTypeDescription
host_pathimpl AsRef<Path>Path on the host filesystem
guest_path&strDestination path inside the sandbox

​
copy_to_host()

async fn copy_to_host(&self, guest_path: &str, host_path: impl AsRef<Path>) -> MicrosandboxResult<()>
Copy a file from the sandbox to the host machine. Parameters
NameTypeDescription
guest_path&strPath inside the sandbox
host_pathimpl AsRef<Path>Destination path on the host

​
exists()

async fn exists(&self, path: &str) -> MicrosandboxResult<bool>
Check whether a path exists inside the sandbox. Parameters
NameTypeDescription
path&strAbsolute path inside the guest
Returns
TypeDescription
booltrue if the path exists

​
list()

async fn list(&self, path: &str) -> MicrosandboxResult<Vec<FsEntry>>
List the entries in a directory. Returns metadata for each entry including name, type, size, and permissions. Parameters
NameTypeDescription
path&strAbsolute directory path inside the guest
Returns
TypeDescription
Vec<FsEntry>Directory entries

​
mkdir()

async fn mkdir(&self, path: &str) -> MicrosandboxResult<()>
Create a directory. Parent directories must already exist. Parameters
NameTypeDescription
path&strAbsolute directory path

​
read()

async fn read(&self, path: &str) -> MicrosandboxResult<Bytes>
Read the entire contents of a file as raw bytes. Parameters
NameTypeDescription
path&strAbsolute path inside the guest (e.g. "/app/config.json")
Returns
TypeDescription
BytesFile contents as raw bytes

​
read_stream()

async fn read_stream(&self, path: &str) -> MicrosandboxResult<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, or when you want to process data incrementally. Parameters
NameTypeDescription
path&strAbsolute path inside the guest
Returns
TypeDescription
FsReadStreamAsync stream that yields chunks of file data

​
read_to_string()

async fn read_to_string(&self, path: &str) -> MicrosandboxResult<String>
Read the entire contents of a file and decode as UTF-8. Returns an error if the file contains invalid UTF-8. Parameters
NameTypeDescription
path&strAbsolute path inside the guest
Returns
TypeDescription
StringFile contents as a UTF-8 string

​
remove()

async fn remove(&self, path: &str) -> MicrosandboxResult<()>
Remove a file. Parameters
NameTypeDescription
path&strAbsolute file path

​
remove_dir()

async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()>
Remove a directory. Parameters
NameTypeDescription
path&strAbsolute directory path

​
rename()

async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()>
Rename or move a file or directory within the sandbox. Parameters
NameTypeDescription
from&strCurrent path
to&strNew path

​
stat()

async fn stat(&self, path: &str) -> MicrosandboxResult<FsMetadata>
Get detailed metadata for a file or directory, including type, size, permissions, and timestamps. Parameters
NameTypeDescription
path&strAbsolute path inside the guest
Returns
TypeDescription
FsMetadataFile metadata

​
write()

async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()>
Write content to a file, creating it if it doesn’t exist and overwriting if it does. Parent directories must already exist. Parameters
NameTypeDescription
path&strAbsolute path inside the guest
dataimpl AsRef<[u8]>File content

​
write_stream()

async fn write_stream(&self, path: &str) -> MicrosandboxResult<FsWriteSink>
Open a streaming writer for large files. Write chunks incrementally and close when done. Parameters
NameTypeDescription
path&strAbsolute path inside the guest
Returns
TypeDescription
FsWriteSinkAsync writer for sending chunks

​
Types

​
FsEntry

Metadata for a single directory entry, returned by list().
FieldTypeDescription
kindFsEntryKindType of entry
modeu32Unix permission bits (e.g. 0o644)
modifiedOption<DateTime<Utc>>Last modified timestamp
pathStringFile path
sizeu64File size in bytes

​
FsEntryKind

The type of a filesystem entry.
ValueDescription
DirectoryDirectory
FileRegular file
OtherOther entry type (device, socket, etc.)
SymlinkSymbolic link

​
FsMetadata

Detailed file metadata, returned by stat().
FieldTypeDescription
createdOption<DateTime<Utc>>Creation timestamp (not available on all filesystems)
kindFsEntryKindType of entry
modeu32Unix permission bits
modifiedOption<DateTime<Utc>>Last modified timestamp
readonlyboolWhether the file is read-only
sizeu64File size in bytes

​
FsReadStream

Async stream for reading a file in chunks. Obtained via read_stream().
MethodReturnsDescription
collect()BytesCollect all remaining chunks into a single Bytes buffer.
recv()Option<Bytes>Receive the next chunk. Returns None when the file has been fully read.

​
FsWriteSink

Async writer for streaming data into a file. Obtained via write_stream().
MethodParametersDescription
close()-Finalize the write and close the stream. Must be called to ensure all data is flushed.
write()data: impl AsRef<[u8]>Write a chunk of data to the file.