Sandbox file system: read, write, and manage files

Read, write, list, and delete files inside a Blaxel sandbox using a simple file system interface from the SDK, MCP server, or REST API.

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:

TypeScript

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:

TypeScript

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:

TypeScript

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:

TypeScript

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:

TypeScript

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:

TypeScript

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.

TypeScript

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:

TypeScript

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:

TypeScript

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

If you’re calling the sandbox filesystem API directly over HTTP instead of using an SDK, a single request is capped at 5 MB. Requests larger than this are rejected with an HTTP 413 before they reach the sandbox. Therefore, if using HTTP, larger files must be uploaded in parts via the sandbox’s multipart upload endpoints rather than in a single request. Blaxel SDKs handle this automatically: SDK functions like write(), writeBinary(), and write_binary() automatically split files over 5 MB and send via multipart upload in 5 MB chunks.

Download file to host

Download a file from the sandbox filesystem to the host:

TypeScript

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:

TypeScript

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:

TypeScript

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:

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

TypeScript

// 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 /**:

TypeScript

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:

TypeScript

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.