File system - Documentation

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

Learn more about authentication on Blaxel

The Blaxel SDK requires two environment variables to authenticate:

Variable	Description
`BL_WORKSPACE`	Your Blaxel workspace name
`BL_API_KEY`	Your 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");

from blaxel.core import SandboxInstance

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

result = await sandbox.fs.ls("/blaxel/app")
directories = result.subdirectories
files = result.files

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.");
}

result = await sandbox.fs.find(
    path="/app",
    type="file",
    patterns=["*.md", "*.html"],
    max_results=1000,
)
if result.matches:
    for file in result.matches:
        logger.info(f"Found file: {file.path}")
else:
    logger.info("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.");
}

result = await sandbox.fs.grep(
    query="agentic",
    path="/app",
    case_sensitive=True,
    context_lines=2,
    max_results=5,
    file_pattern="*.mdx",
    exclude_dirs=["images", "node_modules"],
)
if result.matches:
    for match in result.matches:
        logger.info(
            f"{match.path}:{match.line} -> {match.text}"
        )
else:
    logger.info("No matches found.")

Read file

Read a file from a specific filepath:

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

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", "{}");

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

files = [
    {"path": "src/app.py", "content": "print('Hello')"},
    {"path": "src/utils.py", "content": "def helper(): pass"},
    {"path": "requirements.txt", "content": "flask==2.0.1"},
    {"path": "docs/README.md", "content": "# My App"}
]
await sandbox.fs.write_tree(files, "/blaxel/app")

Read binary file

Read a binary file from the sandbox filesystem:

const binaryData = await sandbox.fs.readBinary("/tmp/image.webp");

binary_data = await sandbox.fs.read_binary("/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);

with open("image.webp", "rb") as f:
    binary_data = f.read()
    await sandbox.fs.write_binary("/blaxel/app/assets/image.webp", binary_data)

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

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

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`);

await sandbox.fs.rm(f"/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:

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
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();

def watch_callback(file_event):
  print(file_event.op, file_event.path, file_event.content)

# You can specify if you want the content of the files or not
handle = sandbox.fs.watch("/", watch_callback, { "with_content": 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)
});

def watch_callback(file_event):
  print(file_event.op, file_event.path)

# You can specify if you want the content of the files or not
handle = sandbox.fs.watch("/folder/**", watch_callback)

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"]
});

def watch_callback(file_event):
  print(file_event.op, file_event.path)

# You can specify if you want the content of the files or not
handle = sandbox.fs.watch("/", watch_callback, {
  "ignore": ["/folder", "/folder_two/test2.txt"]
})

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

​Basic file system operations

​Create directory

​List files

​Find files and directories

​Search for text content within files

​Read file

​Write file

​Write multiple files

​Read binary file

​Write binary file

​Download file to host

​Copy file

​Delete file or directory

​Watch filesystem for events

​Watch sub-directories

​Ignore files or directories

Basic file system operations

Create directory

List files

Find files and directories

Search for text content within files

Read file

Write file

Write multiple files

Read binary file

Write binary file

Download file to host

Copy file

Delete file or directory

Watch filesystem for events

Watch sub-directories

Ignore files or directories