Skip to main content
Use the file API to inspect paths, read and write content, move files, watch directories, and generate presigned transfer URLs.

​
Read and Write Files

Read and write text or bytes: 
await sandbox.files.writeText("/tmp/hello.txt", "hello from sandbox");

const text = await sandbox.files.readText("/tmp/hello.txt");
const bytes = await sandbox.files.readBytes("/tmp/hello.txt");

console.log(text);
console.log(bytes.toString("utf8"));
Batch writes are also supported: 
await sandbox.files.write([
  { path: "/tmp/a.txt", data: "alpha" },
  { path: "/tmp/b.bin", data: Buffer.from([1, 2, 3]) },
]);

​
List and Inspect Paths

Get rich metadata for files and directories: 
const exists = await sandbox.files.exists("/tmp/hello.txt");
const info = await sandbox.files.getInfo("/tmp/hello.txt");
const entries = await sandbox.files.list("/tmp", { depth: 1 });

console.log(exists);
console.log(info.permissions, info.owner, info.group);
console.log(entries.map((entry) => entry.path));
You can also use read() for different formats:
  • text
  • bytes
  • blob
  • stream

​
Move, Copy, Upload, and Remove

Move data around inside the sandbox and transfer raw bytes: 
await sandbox.files.makeDir("/tmp/data", { parents: true });
await sandbox.files.writeText("/tmp/data/source.txt", "payload");

await sandbox.files.copy({
  source: "/tmp/data/source.txt",
  destination: "/tmp/data/copied.txt",
});

await sandbox.files.rename("/tmp/data/copied.txt", "/tmp/data/renamed.txt");

const uploaded = await sandbox.files.upload("/tmp/data/upload.txt", "uploaded body");
const downloaded = await sandbox.files.download("/tmp/data/upload.txt");

await sandbox.files.remove("/tmp/data/source.txt");

console.log(uploaded.bytesWritten);
console.log(downloaded.toString("utf8"));

​
Watch a Directory

Watch a directory and receive relative file events: 
const handle = await sandbox.files.watchDir(
  "/tmp/watch",
  async (event) => {
    console.log(event.type, event.name);
  },
  {
    recursive: true,
  }
);

await sandbox.files.writeText("/tmp/watch/example.txt", "hello");

// Stop the watcher when finished
await handle.stop();

​
Presigned Upload and Download URLs

Generate one-time or expiring transfer URLs: 
const upload = await sandbox.files.uploadUrl("/tmp/presigned.txt", {
  oneTime: true,
  expiresInSeconds: 60,
});

const download = await sandbox.files.downloadUrl("/tmp/presigned.txt", {
  oneTime: true,
  expiresInSeconds: 60,
});

console.log(upload.method, upload.url);
console.log(download.method, download.url);

​
Common File Methods

  • exists(path)
  • getInfo(path) / get_info(path)
  • list(path, { depth })
  • read(path, { format, offset, length })
  • readText(path) / read_text(path)
  • readBytes(path) / read_bytes(path)
  • write(path, data)
  • writeText(path, data) / write_text(path, data)
  • writeBytes(path, data) / write_bytes(path, data)
  • makeDir(path) / make_dir(path)
  • rename(oldPath, newPath)
  • copy({ source, destination, recursive, overwrite })
  • upload(path, data)
  • download(path)
  • chmod({ path, mode })
  • chown({ path, uid, gid })
  • remove(path, { recursive })
  • watchDir(path, ...) / watch_dir(path, ...)
  • uploadUrl(path, ...) / upload_url(path, ...)
  • downloadUrl(path, ...) / download_url(path, ...)