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.

​
copy()

copy(from: string, to: string): Promise<void>
Copy a file within the sandbox. Parameters
NameTypeDescription
fromstringSource path
tostringDestination path

​
copyFromHost()

copyFromHost(hostPath: string, guestPath: string): Promise<void>
Copy a file from the host machine into the sandbox. For transferring many files, consider a bind-mounted volume instead. Parameters
NameTypeDescription
hostPathstringPath on the host filesystem
guestPathstringDestination path inside the sandbox

​
copyToHost()

copyToHost(guestPath: string, hostPath: string): Promise<void>
Copy a file from the sandbox to the host machine. Parameters
NameTypeDescription
guestPathstringPath inside the sandbox
hostPathstringDestination path on the host

​
exists()

exists(path: string): Promise<boolean>
Check whether a path exists inside the sandbox. Parameters
NameTypeDescription
pathstringAbsolute path inside the guest
Returns
TypeDescription
booleantrue if the path exists

​
list()

list(path: string): Promise<Array<FsEntry>>
List the entries in a directory. Parameters
NameTypeDescription
pathstringAbsolute directory path inside the guest
Returns
TypeDescription
Array<FsEntry>Directory entries

​
mkdir()

mkdir(path: string): Promise<void>
Create a directory. Parent directories must already exist. Parameters
NameTypeDescription
pathstringAbsolute directory path

​
read()

read(path: string): Promise<Buffer>
Read the entire contents of a file as raw bytes. Parameters
NameTypeDescription
pathstringAbsolute path inside the guest (e.g. "/app/config.json")
Returns
TypeDescription
BufferFile contents as raw bytes

​
readStream()

readStream(path: string): Promise<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
pathstringAbsolute path inside the guest
Returns
TypeDescription
FsReadStreamAsync stream that yields chunks of file data

​
readString()

readString(path: string): Promise<string>
Read the entire contents of a file and decode as UTF-8. Parameters
NameTypeDescription
pathstringAbsolute path inside the guest
Returns
TypeDescription
stringFile contents as a string

​
remove()

remove(path: string): Promise<void>
Remove a file. Parameters
NameTypeDescription
pathstringAbsolute file path

​
removeDir()

removeDir(path: string): Promise<void>
Remove a directory. Parameters
NameTypeDescription
pathstringAbsolute directory path

​
rename()

rename(from: string, to: string): Promise<void>
Rename or move a file or directory within the sandbox. Parameters
NameTypeDescription
fromstringCurrent path
tostringNew path

​
stat()

stat(path: string): Promise<FsMetadata>
Get detailed metadata for a file or directory. Parameters
NameTypeDescription
pathstringAbsolute path inside the guest
Returns
TypeDescription
FsMetadataFile metadata

​
write()

write(path: string, data: Buffer): Promise<void>
Write content to a file, creating it if it doesn’t exist and overwriting if it does. Parent directories must already exist. Parameters
NameTypeDescription
pathstringAbsolute path inside the guest
dataBufferFile content

​
Types

​
FsEntry

Metadata for a single directory entry, returned by list().
FieldTypeDescription
kindFsEntryKindType of entry
modenumberUnix permission bits
modified?numberLast modified timestamp (ms since epoch)
pathstringFile path
sizenumberFile size in bytes

​
FsEntryKind

ValueDescription
'directory'Directory
'file'Regular file
'other'Other entry type
'symlink'Symbolic link

​
FsMetadata

Detailed file metadata, returned by stat().
FieldTypeDescription
created?numberCreation timestamp (ms since epoch)
kindFsEntryKindType of entry
modenumberUnix permission bits
modified?numberLast modified timestamp (ms since epoch)
readonlybooleanWhether the file is read-only
sizenumberFile size in bytes

​
FsReadStream

Async stream for reading a file in chunks. Obtained via readStream().
MethodReturnsDescription
[Symbol.asyncIterator]AsyncGenerator<Buffer>Use with for await...of
recv()Promise<Buffer | null>Receive the next chunk. Returns null when the file has been fully read.