File System

Every sandbox has a persistent file system in the default working directory: /project/workspace. All files saved in /project/workspace have git source control and will be persisted between reboots. Whenever we hibernate or shutdown a sandbox, we create a commit to track the filesystem of the sandbox.

Refer to the Persistence section for more information about how we store files and other resources.

API

The API of the filesystem is similar to the Node.js fs module. You can find the API under sandbox.fs. All filesystem operations are relative to the workspace directory of the sandbox (which is /project/workspace by default).

Writing & Reading Files

You can read & write files using an api that's similar to the Node.js fs module:

// Writing text files
await client.fs.writeTextFile("./hello.txt", "Hello, world!");
 
// Reading text files
const content = await client.fs.readTextFile("./hello.txt");
console.log(content);
 
// Writing binary files
await client.fs.writeFile("./hello.bin", new Uint8Array([1, 2, 3]));
 
// Reading binary files
const content = await client.fs.readFile("./hello.bin");
console.log(content);

Batch write files

If you need to write a lot of files, you can batch write instead. This will compress the files into a single file, upload that file and then uncompress them on the Sandbox. If the path of files match an existing file, it will be overridden.

await client.fs.batchWrite([
  {
    // The path to write the contents to (relative to workspace)
    path: "src/index.html",
    content: "hello world",
  },
  {
    path: "src/foo.bin",
    // You can also write binary files
    content: new Uint8Array([1, 2, 3])
  },
]);

Uploading & Downloading Files

Uploading and downloading files can be done using the same methods.

import fs from "node:fs";
 
const myBinaryFile = fs.readFileSync("./my-binary-file");
await client.fs.writeFile("./my-binary-file", myBinaryFile);
 
const content = await client.fs.readFile("./my-binary-file");
fs.writeFileSync("./my-binary-file", content);

You can also download a file or directory as a zip file by generating a download URL. This URL is valid for 5 minutes:

const { downloadUrl } = await client.fs.download("./");
console.log(downloadUrl);

Listing Files & Directories

You can list files & directories in a directory using the readdir method.

const filesOrDirs = await client.fs.readdir("./");
 
console.log(filesOrDirs);

Copying, Renaming & Deleting Files

You can copy, rename & delete files using the copy, rename & remove methods.

await client.fs.copy("./hello.txt", "./hello-copy.txt");
await client.fs.rename("./hello-copy.txt", "./hello-renamed.txt");
await client.fs.remove("./hello-renamed.txt");

Watching Files

You can watch files for file changes, additions and deletions using the watch method.

const watcher = await client.fs.watch("./", { recursive: true, excludes: [".git"] });
 
watcher.onEvent((event) => {
  console.log(event);
});
 
// When you're done, you can stop the watcher
watcher.dispose();

Storage (Mounts)

You can learn more about the different folders to store files in the Sessions documentation.

Clients Terminals