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).
Reading and Writing
Section titled “Reading and Writing”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") # strraw = sbx.files.read("data/input.csv", format="bytes") # bytesfor 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)await sbx.files.write("data/input.csv", "a,b\n1,2\n");await sbx.files.write([ { path: "app/main.py", data: "print('hi')\n" }, { path: "app/run.sh", data: "python3 app/main.py\n", mode: 0o755 },]);const text = await sbx.files.read("data/input.csv"); // stringconst raw = await sbx.files.read("data/input.csv", { format: "bytes" }); // Uint8Arrayfor (const e of await sbx.files.list("app")) console.log(e.name, e.type, e.size, e.permissions);const exists = await sbx.files.exists("app/main.py");const created = await sbx.files.makeDir("out/reports");await sbx.files.rename("data/input.csv", "data/archive/input.csv");await sbx.files.remove("out");try { await sbx.files.read("missing.txt");} catch (e) { if (e instanceof FileNotFoundError) console.log("not found:", e.target);}sb.Files.Write(ctx, "data/input.csv", []byte("a,b\n1,2\n"))sb.Files.WriteFiles(ctx, []sandbox.WriteEntry{ {Path: "app/main.py", Data: []byte("print('hi')\n")}, {Path: "app/run.sh", Data: []byte("python3 app/main.py\n"), Mode: 0o755},})data, _ := sb.Files.Read(ctx, "data/input.csv")entries, _ := sb.Files.List(ctx, "app")for _, e := range entries { fmt.Println(e.Name, e.Type, e.Size, e.Permissions)}exists, _ := sb.Files.Exists(ctx, "app/main.py")created, _ := sb.Files.MakeDir(ctx, "out/reports")sb.Files.Rename(ctx, "data/input.csv", "data/archive/input.csv")sb.Files.Remove(ctx, "out")var nf *sandbox.NotFoundErrorif _, err := sb.Files.Read(ctx, "missing.txt"); errors.As(err, &nf) { fmt.Println("not found:", nf.Name)}sbx.files.write("data/input.csv", "a,b\n1,2\n").await?;sbx.files .write_files(vec![ WriteEntry { path: "app/main.py".into(), data: b"print('hi')\n".to_vec(), ..Default::default() }, WriteEntry { path: "app/run.sh".into(), data: b"python3 app/main.py\n".to_vec(), mode: 0o755, }, ]) .await?;let text = sbx.files.read_text("data/input.csv").await?; // Stringlet raw = sbx.files.read("data/input.csv").await?; // Vec<u8>for e in sbx.files.list("app").await? { println!("{} {} {} {}", e.name, e.file_type, e.size, e.permissions);}let exists = sbx.files.exists("app/main.py").await?;let created = sbx.files.make_dir("out/reports").await?;sbx.files .rename("data/input.csv", "data/archive/input.csv") .await?;sbx.files.remove("out").await?;if let Err(Error::NotFound { name, .. }) = sbx.files.read("missing.txt").await { println!("not found: {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(uploadkeeps the local file’s mode, andwrite_files/WriteFilestake amodeper 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,dirorsymlink; in Rustfile_type, aFileType);size,mode(permission bits),permissions(rwxr-xr-x),owner,group;modified_time/modifiedTime/ModifiedTime, andsymlink_targetfor 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")await sbx.files.upload("./local/model.bin", "models/model.bin");await sbx.files.download("results/out.json", "./out/out.json");await sbx.files.uploadDir("./my-project", "/work/project");await sbx.files.downloadDir("/work/project/build", "./build");sb.Files.Upload(ctx, "./local/model.bin", "models/model.bin")sb.Files.Download(ctx, "results/out.json", "./out/out.json")sb.Files.UploadDir(ctx, "./my-project", "/work/project")sb.Files.DownloadDir(ctx, "/work/project/build", "./build")sbx.files .upload("./local/model.bin", "models/model.bin") .await?;sbx.files .download("results/out.json", "./out/out.json") .await?;sbx.files .upload_dir("./my-project", "/work/project") .await?;sbx.files .download_dir("/work/project/build", "./build") .await?;upload/downloadcopy one file.downloadcreates local parent directories.upload_dir/uploadDir/UploadDirsend 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/DownloadDirfetch 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.
