Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

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, in Python, and in Go.

​
Basic file system operations

The Blaxel SDK requires two environment variables to authenticate:
VariableDescription
BL_WORKSPACEYour Blaxel workspace name
BL_API_KEYYour Blaxel API key
You can create an API key from the Blaxel console. Your workspace name is visible in the URL when you log in to the console (e.g. app.blaxel.ai/{workspace}).Set them as environment variables or add them to a .env file at the root of your project:
export BL_WORKSPACE=my-workspace
export BL_API_KEY=my-api-key
The Blaxel SDK does not accept credentials as constructor arguments. Credentials must come from environment variables, a .env file, or a local CLI login session (see below).When developing locally, you can also log in to your workspace with Blaxel CLI (as shown above). This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, authentication is handled automatically — no environment variables needed.

​
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");

​
Find files and directories

Blaxel’s Sandbox API uses an optimized find() method, which is faster than using the native find tool.
Find files and directories matching specified patterns: 
let result = await sandbox.fs.find(
  "/app",
  {
    type: "file",
    patterns: ["*.md", "*.html"],
    maxResults: 1000,
  }
);

if (result.matches && result.matches.length > 0) {
  for (const file of result.matches) {
    console.log(`Found file: ${file.path}`);
  }
} else {
  console.log("No files found.");
}

​
Search for text content within files

Blaxel’s Sandbox API uses an optimized grep() method, which is faster than using the native grep tool.
Find files containing specified text content: 
let result = await sandbox.fs.grep(
  "agentic",
  "/app",
  {
    caseSensitive: true,
    contextLines: 2,
    maxResults: 5,
    filePattern: "*.mdx",
    excludeDirs: ["images", "node_modules"],
  }
);

if (result.matches && result.matches.length > 0) {
  for (const match of result.matches) {
    console.log(`${match.path}:${match.line} -> ${match.text}`);
  }
} else {
  console.log("No matches found.");
}

​
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");

​
Read binary file

Read a binary file from the sandbox filesystem: 
const binaryData = await sandbox.fs.readBinary("/tmp/image.webp");
The binary content is returned as a Web API Blob object.

​
Write binary file

Write binary content to a file in the sandbox filesystem: 
const binaryData = fs.readFileSync("./image.webp");
await sandbox.fs.writeBinary("/blaxel/app/assets/image.webp", 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

​
Download file to host

Download a file from the sandbox filesystem to the host: 
await sandbox.fs.download("/tmp/foo.bin", "foo2.bin");

​
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.
Last modified on May 1, 2026