File system

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.

Refer to our blog post on choosing the right storage for your Blaxel agents for more information.

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

Address file paths over HTTP

Filesystem paths are part of the URL when you call the sandbox API directly over HTTP. The API resolves a path without a leading slash relative to the filesystem service’s working directory. To address an absolute path, URL-encode the leading slash as %2F. For example, if the filesystem working directory is /app:

Request path	Resolved filesystem path
`/filesystem/workspace`	`/app/workspace`
`/filesystem/%2Fworkspace`	`/workspace`

The CLI’s double-slash form, such as --path /filesystem//workspace, is the CLI equivalent for an absolute path. For a direct HTTP request, use %2F for the leading slash:

curl -X GET \
  "https://sbx-{YOUR-SANDBOX}-{YOUR-WORKSPACE}.{REGION}.bl.run/filesystem/%2Fworkspace" \
  -H "X-Blaxel-Authorization: Bearer <YOUR_API_KEY>"

The same rule applies when initiating a multipart upload. The following example starts an upload to the absolute path /workspace/archive.tar, uploads one part, and completes the upload. Repeat the part request with increasing partNumber values for additional parts, then include every returned etag in the completion request.

# Initiate an upload to /workspace/archive.tar.
curl -X POST \
  "https://sbx-{YOUR-SANDBOX}-{YOUR-WORKSPACE}.{REGION}.bl.run/filesystem-multipart/initiate/%2Fworkspace/archive.tar" \
  -H "X-Blaxel-Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"permissions":"0644"}'

# Use the uploadId returned above to upload each part.
curl -X PUT \
  "https://sbx-{YOUR-SANDBOX}-{YOUR-WORKSPACE}.{REGION}.bl.run/filesystem-multipart/<UPLOAD_ID>/part?partNumber=1" \
  -H "X-Blaxel-Authorization: Bearer <YOUR_API_KEY>" \
  -F "file=@archive.part-1"

# Complete the upload with the etag returned for each part.
curl -X POST \
  "https://sbx-{YOUR-SANDBOX}-{YOUR-WORKSPACE}.{REGION}.bl.run/filesystem-multipart/<UPLOAD_ID>/complete" \
  -H "X-Blaxel-Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"partNumber":1,"etag":"<PART_1_ETAG>"}]}'

This URL-encoding requirement applies only when the filesystem path is embedded in an HTTP URL. SDK filesystem methods accept normal paths such as /workspace.

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

Read many files

Discover relative file paths with fs.find, then read text files in batches of four. This returns flat path/content pairs with one discovery call plus one read call per file, not a single bulk-read request. find defaults to 20 results, so do not assume its default response includes every file. Request one more than your chosen file cap and reject the result if that extra match is returned. excludeDirs (exclude_dirs in Python) matches directory names, not path globs; apply file exclusions by filtering paths separately.

const root = "/blaxel/app/schemas";
const maxFiles = 20;
const result = await sandbox.fs.find(root, {
  type: "file",
  patterns: ["*.json"],
  excludeDirs: ["node_modules", ".git"],
  maxResults: maxFiles + 1,
});
const matches = result.matches ?? [];
if (matches.length > maxFiles) {
  throw new Error("File cap exceeded; narrow your search.");
}

const files: Array<{ path: string; content: string }> = [];
for (let offset = 0; offset < matches.length; offset += 4) {
  const batch = await Promise.all(
    matches.slice(offset, offset + 4).map(async (file) => ({
      path: file.path,
      content: await sandbox.fs.read(`${root}/${file.path}`),
    }))
  );
  files.push(...batch);
}

import asyncio

root = "/blaxel/app/schemas"
max_files = 20
result = await sandbox.fs.find(
    root,
    type="file",
    patterns=["*.json"],
    exclude_dirs=["node_modules", ".git"],
    max_results=max_files + 1,
)
matches = result.matches or []
if len(matches) > max_files:
    raise ValueError("File cap exceeded; narrow your search.")

async def read_file(file):
    return {
        "path": file.path,
        "content": await sandbox.fs.read(f"{root}/{file.path}"),
    }

files = []
for offset in range(0, len(matches), 4):
    batch = await asyncio.gather(
        *(read_file(file) for file in matches[offset:offset + 4])
    )
    files.extend(batch)

Export a whole directory as one archive

Create an archive on disk with tar, then download it with one binary read. This uses two calls for creation and download, plus a cleanup call. Your sandbox image must include tar. Keep the temporary archive outside the directory you are exporting.

import { randomUUID } from "node:crypto";

const archivePath = `/tmp/schemas-${randomUUID()}.tar.gz`;
let archiveData: Blob;
try {
  const result = await sandbox.process.exec({
    command: `tar -czf '${archivePath}' -C '/blaxel/app/schemas' .`,
    waitForCompletion: true,
    timeout: 30,
  });
  if (result.exitCode !== 0) {
    throw new Error("Archive creation failed.");
  }
  archiveData = await sandbox.fs.readBinary(archivePath);
} finally {
  await sandbox.fs.rm(archivePath);
}

from uuid import uuid4

archive_path = f"/tmp/schemas-{uuid4()}.tar.gz"
try:
    result = await sandbox.process.exec({
        "command": f"tar -czf '{archive_path}' -C '/blaxel/app/schemas' .",
        "wait_for_completion": True,
        "timeout": 30,
    })
    if result.exit_code != 0:
        raise RuntimeError("Archive creation failed.")
    archive_data = await sandbox.fs.read_binary(archive_path)
finally:
    await sandbox.fs.rm(archive_path)

Do not pipe base64-encoded file contents through process logs. Output can be truncated, and file contents are exposed in retained logs. Use the binary filesystem read instead.

Neither recipe guarantees a consistent snapshot if files change during the operation.

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

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:

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.

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Applications

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Basic file system operations

Create directory

List files

Address file paths over HTTP

Find files and directories

Search for text content within files

Read file

Read many files

Export a whole directory as one archive

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

​Address file paths over HTTP

​Find files and directories

​Search for text content within files

​Read file

​Read many files

​Export a whole directory as one archive

​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

Address file paths over HTTP

Find files and directories

Search for text content within files

Read file

Read many files

Export a whole directory as one archive

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