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.

upload_file()

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

Python

def upload_file(content: bytes, remote_path: str, timeout: int = 1800) -> None

Parameter	Type	Default	Description
`content`	`bytes`	—	File contents.
`remote_path`	`str`	—	Destination path inside the sandbox.
`timeout`	`int`	`1800`	Request timeout in seconds.

Python

sandbox.fs.upload_file(b"hello\n", "/workspace/hello.txt")

download_file()

Downloads a file's bytes from the sandbox.

Python

def download_file(remote_path: str, timeout: int = 1800) -> bytes

Returns: the raw file contents as bytes.

Python

data = sandbox.fs.download_file("/workspace/report.pdf")
open("report.pdf", "wb").write(data)

list_files()

Lists the entries of a directory.

Python

def list_files(path: str) -> List[Dict[str, Any]]

Returns: a list of file-info dicts (name, size, directory flag, mode, timestamps).

get_file_details()

Fetches info for a single file or directory.

Python

def get_file_details(path: str) -> Dict[str, Any]

create_folder()

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

Python

def create_folder(path: str, mode: str) -> None

Parameter	Type	Default	Description
`path`	`str`	—	Directory to create.
`mode`	`str`	—	Octal permission string, e.g. `"755"`.

Python

sandbox.fs.create_folder("/workspace/data", "755")

delete_file()

Deletes a file at the given path.

Python

def delete_file(path: str) -> None

move_files()

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

Python

def move_files(source: str, destination: str) -> None

find_files()

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

Python

def find_files(path: str, pattern: str) -> List[Dict[str, Any]]

Returns: a list of match dicts (file, line, content).

Python

matches = sandbox.fs.find_files("/workspace", "TODO")

search_files()

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

Python

def search_files(path: str, pattern: str) -> Dict[str, Any]

Returns: a dict with a files list of matching paths.

replace_in_files()

Replaces text across a set of files in one call.

Python

def replace_in_files(files: List[str], pattern: str, new_value: str) -> List[Dict[str, Any]]

Parameter	Type	Default	Description
`files`	`List[str]`	—	Paths of files to edit.
`pattern`	`str`	—	Pattern to replace.
`new_value`	`str`	—	Replacement text.

Returns: a list of per-file result dicts (file, success/error).

set_file_permissions()

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

Python

def set_file_permissions(
    path: str,
    mode: str | None = None,
    owner: str | None = None,
    group: str | None = None,
) -> None

Parameter	Type	Default	Description
`path`	`str`	—	Target file.
`mode`	`str`	`None`	Octal permission string, e.g. `"644"`.
`owner`	`str`	`None`	New owner user.
`group`	`str`	`None`	New owner group.

Python

sandbox.fs.set_file_permissions("/workspace/run.sh", mode="755")

On this page