FileSystem

FileSystem performs file operations inside a sandbox via the toolbox. Obtain it as sandbox.fs. All paths are paths inside the sandbox. See the files guide for a task-oriented walkthrough.

uploadFile()

Uploads a Buffer to a path inside the sandbox. The default timeout is generous (30 minutes) to accommodate large uploads.

uploadFile(file: Buffer, remotePath: string, timeout: number = 30 * 60): Promise<void>

await sandbox.fs.uploadFile(Buffer.from('hello\n'), '/workspace/hello.txt')

downloadFile()

Downloads a file's bytes from the sandbox.

downloadFile(remotePath: string, timeout: number = 30 * 60): Promise<Buffer>

Returns: the raw file contents as a Buffer.

const data = await sandbox.fs.downloadFile('/workspace/report.pdf')
await fs.promises.writeFile('report.pdf', data)

listFiles()

Lists the entries of a directory.

listFiles(path: string): Promise<FileInfo[]>

Returns: FileInfo[] — { name, isDir, size, modTime?, mode?, permissions?, owner?, group? }.

getFileDetails()

Fetches info for a single file or directory.

getFileDetails(path: string): Promise<FileInfo>

createFolder()

Creates a folder at the given path with the given permission mode.

createFolder(path: string, mode: string): Promise<void>

await sandbox.fs.createFolder('/workspace/data', '755')

deleteFile()

Deletes a file at the given path.

deleteFile(path: string): Promise<void>

moveFiles()

Moves (renames) a file or directory from source to destination.

moveFiles(source: string, destination: string): Promise<void>

findFiles()

Searches for text inside files under a path — grep-style. Compare searchFiles(), which matches file names.

findFiles(path: string, pattern: string): Promise<Match[]>

Returns: Match[] — { file, line, content }.

const matches = await sandbox.fs.findFiles('/workspace', 'TODO')

searchFiles()

Searches for files whose names match a pattern under a path.

searchFiles(path: string, pattern: string): Promise<SearchFilesResponse>

Returns: { files: string[] }.

replaceInFiles()

Replaces text across a set of files in one call.

replaceInFiles(files: string[], pattern: string, newValue: string): Promise<ReplaceResult[]>

Returns: ReplaceResult[] — { file, success?, error? } per file.

setFilePermissions()

Sets permissions and/or ownership on a file. Any subset of mode, owner, and group may be provided in the params object.

setFilePermissions(path: string, permissions: FilePermissionsParams): Promise<void>

await sandbox.fs.setFilePermissions('/workspace/run.sh', { mode: '755' })