Files

sandbox.files.write

Write text or bytes to a file in a running sandbox.

TypeScript

sandbox.files.write(path: string, data: string | Uint8Array, options?: WriteOptions): Promise<void>

Python

sandbox.files.write(path, data, *, size=None, mode=None, parents=False, user=None) -> None

Examples

TypeScript

await sandbox.files.write("/root/notes.txt", "hello\n");
await sandbox.files.write("/srv/app/run.sh", "#!/bin/sh\necho up\n", { mode: 0o755, parents: true });

Python

sandbox.files.write("/root/notes.txt", "hello\n")
sandbox.files.write("/srv/app/run.sh", "#!/bin/sh\necho up\n", mode=0o755, parents=True)
with open("data.bin", "rb") as f:
    sandbox.files.write("/root/data.bin", f)

Arguments

Argument	Description
path	absolute path in the sandbox
data	a string or bytes; in Python also a binary file or stream

Options

TypeScript	Python	Description
mode	mode	permission bits, such as 0o644
parents	parents	make the missing parent directories
user	user	user name or uid in the sandbox that owns the file
	size	length of a stream whose length is not known up front

In Python, a seekable file is written from where it stands to its end. A stream that cannot seek needs size, or the call raises UnknownLengthError, and a size that does not match the data raises ValueError.

sandbox.files.read

Read a file in a running sandbox.

TypeScript

sandbox.files.read(path: string): Promise<Uint8Array>
sandbox.files.read(path: string, options: { encoding: "utf8" }): Promise<string>

Python

sandbox.files.read(path) -> bytes
sandbox.files.read_text(path, encoding="utf-8") -> str

Examples

TypeScript

const bytes = await sandbox.files.read("/root/data.bin");
const text = await sandbox.files.read("/root/notes.txt", { encoding: "utf8" });

Python

data = sandbox.files.read("/root/data.bin")
text = sandbox.files.read_text("/root/notes.txt")

The whole file is held in memory. For a large file, use download.

sandbox.files.stat

Return the type, size, mode, owner and modification time of a path in a running sandbox.

TypeScript

sandbox.files.stat(path: string): Promise<FileInfo>

Python

sandbox.files.stat(path) -> FileInfo

Examples

TypeScript

const info = await sandbox.files.stat("/root/notes.txt");
console.log(info.type, info.size, info.mode.toString(8));

Python

info = sandbox.files.stat("/root/notes.txt")
print(info.type, info.size, oct(info.mode))

A FileInfo holds type (file, dir, symlink or other), size, mode, uid, gid and mtime. mode holds the permission bits with setuid, setgid and sticky.

sandbox.files.list

List the entries of a directory in a running sandbox.

TypeScript

sandbox.files.list(path: string): Promise<FileEntry[]>

Python

sandbox.files.list(path) -> list[FileEntry]

Examples

TypeScript

for (const entry of await sandbox.files.list("/root")) console.log(entry.name, entry.type);

Python

for entry in sandbox.files.list("/root"):
    print(entry.name, entry.type)

Each entry is a FileInfo with a name. A symlink’s entry describes the link itself, never what it points to.

sandbox.files.mkdir

Make a directory in a running sandbox.

TypeScript

sandbox.files.mkdir(path: string, options?: WriteOptions): Promise<void>

Python

sandbox.files.mkdir(path, *, mode=None, parents=False, user=None) -> None

Examples

TypeScript

await sandbox.files.mkdir("/srv/app/data", { parents: true });

Python

sandbox.files.mkdir("/srv/app/data", parents=True)

Options

TypeScript	Python	Description
mode	mode	permission bits, such as 0o755
parents	parents	make the missing parent directories too
user	user	user name or uid in the sandbox that owns the directory

sandbox.files.remove

Delete a path in a running sandbox.

TypeScript

sandbox.files.remove(path: string, options?: { recursive?: boolean }): Promise<void>

Python

sandbox.files.remove(path, *, recursive=False) -> None

Examples

TypeScript

await sandbox.files.remove("/root/notes.txt");
await sandbox.files.remove("/srv/app", { recursive: true });

Python

sandbox.files.remove("/root/notes.txt")
sandbox.files.remove("/srv/app", recursive=True)

Options

TypeScript	Python	Description
recursive	recursive	delete a directory and everything under it

sandbox.files.upload

Copy a local file into a running sandbox without holding it in memory.

TypeScript

sandbox.files.upload(local: string, remote: string, options?: WriteOptions): Promise<void>

Python

sandbox.files.upload(local, remote, *, mode=None, parents=False, user=None) -> None

Examples

TypeScript

await sandbox.files.upload("./dist/app.tar.gz", "/srv/app.tar.gz");

Python

sandbox.files.upload("./dist/app.tar.gz", "/srv/app.tar.gz")

Options

TypeScript	Python	Description
mode	mode	permission bits; the local file’s own by default
parents	parents	make the missing parent directories
user	user	user name or uid in the sandbox that owns the file

The local path must be a regular file, or the call raises UnknownLengthError.

sandbox.files.download

Copy a file out of a running sandbox into a local file, without holding it in memory.

TypeScript

sandbox.files.download(remote: string, local: string): Promise<void>

Python

sandbox.files.download(remote, local) -> None

Examples

TypeScript

await sandbox.files.download("/tmp/results.json", "./results.json");

Python

sandbox.files.download("/tmp/results.json", "./results.json")

The download writes a temporary file next to the local path and renames it at the end, so a cut never leaves half a file. The local file takes the sandbox file’s permission bits.

sandbox.files.uploadDir / upload_dir

Copy a local directory into a running sandbox, as a tar archive.

TypeScript

sandbox.files.uploadDir(local: string, remote: string, options?: { user?: string }): Promise<void>

Python

sandbox.files.upload_dir(local, remote, *, user=None) -> None

Examples

TypeScript

await sandbox.files.uploadDir("./app", "/srv/app");

Python

sandbox.files.upload_dir("./app", "/srv/app")

Options

TypeScript	Python	Description
user	user	user name or uid in the sandbox that owns what the copy makes

remote names the directory itself, not its parent.

sandbox.files.downloadDir / download_dir

Copy a directory out of a running sandbox into a local directory.

TypeScript

sandbox.files.downloadDir(remote: string, local: string): Promise<void>

Python

sandbox.files.download_dir(remote, local) -> None

Examples

TypeScript

await sandbox.files.downloadDir("/srv/app/out", "./out");

Python

sandbox.files.download_dir("/srv/app/out", "./out")

The whole archive arrives before the unpack starts, so a cut never lands half a tree. A local directory the call makes takes the sandbox directory’s permission bits, and one that already exists keeps its own.

For shard cp and where a copy lands, see Run commands and move files.