Skip to main content
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.
Complete code examples demonstrating all operations are available on Blaxel’s GitHub: in TypeScript and in Python.

​
Basic file system operations

The Blaxel SDK authenticates with your workspace using credentials from these sources, in priority order:
  1. when running on Blaxel, authentication is handled automatically
  2. variables in your .env file (BL_WORKSPACE and BL_API_KEY, or see this page for other authentication options).
  3. environment variables from your machine
  4. configuration file created locally when you log in through Blaxel CLI (or deploy on Blaxel)
When developing locally, the recommended method is to just log in to your workspace with Blaxel CLI. This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, this connection persists automatically.When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recommend using environment variables as described in the third option above.

​
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.
⌘I