Skip to content

Guides

Files

sbx.files (Go: sb.Files) reads and writes the sandbox filesystem.

  • Paths: relative paths resolve against /work, and absolute paths are used as-is.
  • Cost: each call is one round trip, about 0.15 s on a warm sandbox, so batch where you can (write([...]) / write_files / WriteFiles, upload_dir).
sbx.files.write("data/input.csv", "a,b\n1,2\n")
sbx.files.write_files([
{"path": "app/main.py", "data": "print('hi')\n"},
{"path": "app/run.sh", "data": "python3 app/main.py\n", "mode": 0o755},
])
text = sbx.files.read("data/input.csv") # str
raw = sbx.files.read("data/input.csv", format="bytes") # bytes
for e in sbx.files.list("app"):
print(e.name, e.type, e.size, e.permissions)
exists = sbx.files.exists("app/main.py")
created = sbx.files.make_dir("out/reports")
sbx.files.rename("data/input.csv", "data/archive/input.csv")
sbx.files.remove("out")
try:
sbx.files.read("missing.txt")
except FileNotFoundError as e:
print("not found:", e.name)
Operation Python TypeScript Go Rust Returns
Read read(path, format="text"); format="bytes" for bytes read(path, {format}), format "text", "bytes" or "blob" Read, ReadText read (bytes), read_text contents
Write one write(path, data), data a str, bytes or file object write(path, data), data a string, Uint8Array, ArrayBuffer or Blob Write(ctx, path, []byte) write(path, data), data anything Into<Vec<u8>> (&str, String, Vec<u8>) WriteInfo
Write many write_files([{path, data, mode?}]) write([{path, data, mode?}]) or writeFiles WriteFiles(ctx, []WriteEntry) write_files(Vec<WriteEntry>) WriteInfo[]
List a directory list(path=".") list(path=".") List list(path) entries, sorted by name
Exists exists(path) exists(path) Exists exists(path) bool
Describe get_info(path) getInfo(path) GetInfo get_info(path) EntryInfo
Make directory (mkdir -p) make_dir(path) makeDir(path) MakeDir make_dir(path) false if it existed
Remove (rm -rf) remove(path) remove(path) Remove remove(path) —
Rename/move rename(old, new) rename(old, new) Rename rename(old, new) EntryInfo at the new path

Write semantics:

  • Atomic replace: a file is written to a temporary file and then renamed into place, so readers never see a partial file.
  • Parents and modes: parent directories are created. The mode is 0644 (upload keeps the local file’s mode, and write_files / WriteFiles take a mode per file).
  • Ownership: files are owned by root.
  • Size: any size works. Data over 15 MiB is staged in 15 MiB pieces and then moved into place, because a single call carries at most 16 MiB. A 17 MiB round trip was verified live.
  • Batches: write([...]) sends one gzip’d tar and unpacks it in one call.

EntryInfo fields:

  • name, path;
  • type (file, dir or symlink; in Rust file_type, a FileType);
  • size, mode (permission bits), permissions (rwxr-xr-x), owner, group;
  • modified_time / modifiedTime / ModifiedTime, and symlink_target for symlinks.

list and get_info don’t follow a final symlink. Names containing a newline aren’t supported by list.

Errors:

Situation Python TypeScript Go Rust
Path doesn’t exist FileNotFoundError FileNotFoundError *NotFoundError Error::NotFound
A directory where a file was expected (or the reverse) InvalidPathError InvalidPathError *InvalidPathError Error::InvalidPath

Moving Files Between Your Machine and the Sandbox

Section titled “Moving Files Between Your Machine and the Sandbox”
sbx.files.upload("./local/model.bin", "models/model.bin")
sbx.files.download("results/out.json", "./out/out.json")
sbx.files.upload_dir("./my-project", "/work/project")
sbx.files.download_dir("/work/project/build", "./build")
  • upload / download copy one file. download creates local parent directories.
  • upload_dir / uploadDir / UploadDir send a whole local tree as one gzip’d tar, unpacked into the remote directory (created if missing). Symlinks travel as links; sockets and devices are skipped.
  • download_dir / downloadDir / DownloadDir fetch a remote tree as a tar and unpack it locally. Entries that would land outside the target directory are refused: absolute names, .., and symlinks pointing out. That way a sandbox can’t write elsewhere on your machine.