Manage files and directories within sandboxes through the fs module of Blaxel SDK. This module provides essential operations for creating, reading, writing, copying, and deleting files and directories.

​

Basic file system operations

​

Create directory

Create a new directory at a specific path in the sandbox:

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");

await sandbox.fs.mkdir("/blaxel/app/uploads");

​

List files

List files in a specific path:

const { subdirectories, files } = await sandbox.fs.ls("/blaxel/app");

​

Read file

Read a file from a specific filepath:

const content = await sandbox.fs.read("/blaxel/app/config.json");

​

Write file

Create a file in a specific path:

await sandbox.fs.write("/blaxel/app/config.json", "{}");

See down below for how to upload/write a binary, or multiple files at once.

​

Write multiple files

You can write multiple files or directories simultaneously. The second path parameter in writeTree specifies the base directory for writing the file tree, eliminating the need to repeat the full path for each file.

const files = [
  { path: "src/app.js", content: "console.log('Hello');" },
  { path: "src/utils.js", content: "export const helper = () => {};" },
  { path: "package.json", content: '{"name": "my-app"}' },
  { path: "docs/README.md", content: "# My App" }
];
await sandbox.fs.writeTree(files, "/blaxel/app");

​

Write binary

Write binary content to a file in the sandbox filesystem:

const binaryData = fs.readFileSync("./image.png");
await sandbox.fs.writeBinary("/blaxel/app/assets/image.png", binaryData);

The binary content to write can be provided as:

• Buffer: Node.js Buffer object
• Blob: Web API Blob object
• File: Web API File object
• Uint8Array: Typed array containing binary data

​

Copy file

Copy a file from a path to another path:

await sandbox.fs.cp("/blaxel/app/config.json", "/blaxel/app/config.backup.json");

​

Delete file or directory

Delete a file or directory by specifying its path:

await sandbox.fs.rm(`/blaxel/app/config.json`);

​

Watch filesystem for events

The watch function monitors all file system changes in the specified directory. You can also watch subdirectories by passing a /my/directory/** pattern.

By default (when withContent: false), the events will only include metadata about the changes, not the actual file contents. Here’s what you’ll get in the callback events:

1. For ALL operations (CREATE, WRITE, DELETE, etc.), you’ll receive:
   1. op: The operation type (e.g., “CREATE”, “WRITE”, “DELETE”)
   2. path: The directory path where the change occurred
   3. name: The name of the file/directory that changed
2. You will NOT receive:
   1. The actual content of the files
   2. File contents for CREATE or WRITE operations

// You can specify if you want the content of the files or not
const handle = sandbox.fs.watch("/", (fileEvent) => {
  console.log(fileEvent.op, fileEvent.path, fileEvent.content)
}, {
  withContent: true
});

// Do file operations

// At the end, close the watch handle
handle.close();

​

Watch sub-directories

Watch all sub-directories recursively with /**:

const handle = sandbox.fs.watch("/folder/**", (fileEvent) => {
  console.log(fileEvent.op, fileEvent.path)
});

​

Ignore files or directories

You can ignore changes in certain files or directories by providing an array of filepaths to ignore:

const handle = sandbox.fs.watch("/", (fileEvent) => {
  console.log(fileEvent.op, fileEvent.path)
}, {
  ignore: ["/folder", "/folder_two/test2.txt"]
});

Specify withContent: true so the events include the actual file contents.