Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Files

Read, write, and manage files in the sandbox filesystem. All paths are absolute (e.g., /workspace/app.js).

Methods

writeFile()

Write content to a file.

TypeScript
await sandbox.writeFile(path: string, content: string, options?: WriteFileOptions): Promise<void>

Parameters:

  • path - Absolute path to the file
  • content - Content to write
  • options (optional):
    • encoding - File encoding ("utf-8" or "base64", default: "utf-8")
JavaScript
await sandbox.writeFile("/workspace/app.js", `console.log('Hello!');`);


// Binary data
await sandbox.writeFile("/tmp/image.png", base64Data, { encoding: "base64" });

Large files and binary data

When using the rpc transport the writeFile() method supports passing a ReadableStream as the content parameter. This allows binary data and files greater than 32 MiB to be written to the sandbox. It replaces the "base64" encoding option.

JavaScript
// Requires SANDBOX_TRANSPORT to be "rpc" in wrangler.jsonc
const req = await fetch("https://example.com/archive.tar.gz");
await sandbox.writeFile('/workspace/archive.tar.gz', req.body);

readFile()

Read a file from the sandbox. By default returns the content as a string. This is useful for small text files. For larger files and binary data use encoding: "none" to get back a ReadableStream with the file data.

TypeScript
const file = await sandbox.readFile(path: string, options?: ReadFileOptions): Promise<ReadFileResult | ReadFileStreamResult>

Parameters:

  • path - Absolute path to the file
  • options (optional):
    • encoding - File encoding ("utf-8", "base64" or "none", default: auto-detected from MIME type)

Returns: Promise<ReadFileResult | ReadFileStreamResult>.

JavaScript
const file = await sandbox.readFile("/workspace/package.json");
const pkg = JSON.parse(file.content);


// Binary data (since 0.10.1 using `rpc` transport)
const { content, size, mimeType } = await sandbox.readFile(
  "/workspace/archive.tar.gz",
  {
    encoding: "none",
  },
);


// Example 1: Store on R2:
const stream = request.body.pipeThrough(new FixedLengthStream(size));
await env.MY_BUCKET.put("/bucket/archive.tar.gz", stream, {
  httpMetadata: { contentType: mimeType },
});


// Example 2: Stream an HTTP response:
return new Response(content, { headers: { "Content-Type": mimeType } });


// Older versions/transports used the base64 encoding for binary data:
const archive = await sandbox.readFile("/workspace/archive.tar.gz", {
  encoding: "base64",
});
console.log(archive.content); // => "<base64 encoded string>";

exists()

Check if a file or directory exists.

TypeScript
const result = await sandbox.exists(path: string): Promise<FileExistsResult>

Parameters:

  • path - Absolute path to check

Returns: Promise<FileExistsResult> with exists boolean

JavaScript
const result = await sandbox.exists("/workspace/package.json");
if (result.exists) {
  const file = await sandbox.readFile("/workspace/package.json");
  // process file
}


// Check directory
const dirResult = await sandbox.exists("/workspace/src");
if (!dirResult.exists) {
  await sandbox.mkdir("/workspace/src");
}

mkdir()

Create a directory.

TypeScript
await sandbox.mkdir(path: string, options?: MkdirOptions): Promise<void>

Parameters:

  • path - Absolute path to the directory
  • options (optional):
    • recursive - Create parent directories if needed (default: false)
JavaScript
await sandbox.mkdir("/workspace/src");


// Nested directories
await sandbox.mkdir("/workspace/src/components/ui", { recursive: true });

deleteFile()

Delete a file.

TypeScript
await sandbox.deleteFile(path: string): Promise<void>

Parameters:

  • path - Absolute path to the file
JavaScript
await sandbox.deleteFile("/workspace/temp.txt");

renameFile()

Rename a file.

TypeScript
await sandbox.renameFile(oldPath: string, newPath: string): Promise<void>

Parameters:

  • oldPath - Current file path
  • newPath - New file path
JavaScript
await sandbox.renameFile("/workspace/draft.txt", "/workspace/final.txt");

moveFile()

Move a file to a different directory.

TypeScript
await sandbox.moveFile(sourcePath: string, destinationPath: string): Promise<void>

Parameters:

  • sourcePath - Current file path
  • destinationPath - Destination path
JavaScript
await sandbox.moveFile("/tmp/download.txt", "/workspace/data.txt");

gitCheckout()

Clone a git repository.

TypeScript
await sandbox.gitCheckout(repoUrl: string, options?: GitCheckoutOptions): Promise<void>

Parameters:

  • repoUrl - Git repository URL
  • options (optional):
    • branch - Branch to checkout (default: repository default branch)
    • targetDir - Directory to clone into (default: /workspace/{repoName})
    • depth - Clone depth for shallow clones (e.g., 1 for latest commit only)
JavaScript
await sandbox.gitCheckout("https://github.com/user/repo");


// Specific branch
await sandbox.gitCheckout("https://github.com/user/repo", {
  branch: "develop",
  targetDir: "/workspace/my-project",
});


// Shallow clone (faster for large repositories)
await sandbox.gitCheckout("https://github.com/facebook/react", {
  depth: 1,
});