---
description: Read, write, organize, and synchronize files in the sandbox.
title: Manage files
image: https://developers.cloudflare.com/og-docs.png
---

[Skip to content](#main-content)

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt  
> Use this file to discover all available pages before exploring further.

# Manage files

Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/sandbox/guides/manage-files/index.md)|[Agent setup](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agent-setup/)

This guide shows you how to read, write, organize, and synchronize files in the sandbox filesystem.

## Path conventions

File operations support both absolute and relative paths:

* `/workspace` \- Default working directory for application files
* `/tmp` \- Temporary files (may be cleared)
* `/home` \- User home directory

```js
// Absolute paths
await sandbox.writeFile("/workspace/app.js", code);

// Relative paths (session-aware)
const session = await sandbox.createSession();
await session.exec("cd /workspace/my-project");
await session.writeFile("app.js", code); // Writes to /workspace/my-project/app.js
await session.writeFile("src/index.js", code); // Writes to /workspace/my-project/src/index.js
```

```plaintext
// Absolute paths
await sandbox.writeFile('/workspace/app.js', code);

// Relative paths (session-aware)
const session = await sandbox.createSession();
await session.exec('cd /workspace/my-project');
await session.writeFile('app.js', code);  // Writes to /workspace/my-project/app.js
await session.writeFile('src/index.js', code);  // Writes to /workspace/my-project/src/index.js
```

## Write files

```js
import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Write text file
await sandbox.writeFile(
	"/workspace/app.js",
	`console.log('Hello from sandbox!');`,
);

// Write JSON
const config = { name: "my-app", version: "1.0.0" };
await sandbox.writeFile(
	"/workspace/config.json",
	JSON.stringify(config, null, 2),
);

// Write binary file (base64)
const buffer = await fetch(imageUrl).then((r) => r.arrayBuffer());
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
await sandbox.writeFile("/workspace/image.png", base64, { encoding: "base64" });
```

```plaintext
import { getSandbox } from '@cloudflare/sandbox';

const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// Write text file
await sandbox.writeFile('/workspace/app.js', `console.log('Hello from sandbox!');`);

// Write JSON
const config = { name: 'my-app', version: '1.0.0' };
await sandbox.writeFile('/workspace/config.json', JSON.stringify(config, null, 2));

// Write binary file (base64)
const buffer = await fetch(imageUrl).then(r => r.arrayBuffer());
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
await sandbox.writeFile('/workspace/image.png', base64, { encoding: 'base64' });
```

## Read files

```js
// Read text file
const file = await sandbox.readFile("/workspace/app.js");
console.log(file.content);

// Read and parse JSON
const configFile = await sandbox.readFile("/workspace/config.json");
const config = JSON.parse(configFile.content);

// Read binary file (v0.10.1 with `rpc` transport)
const imageFile = await sandbox.readFile("/workspace/image.png", {
	encoding: "none",
});
return new Response(imageFile.content, {
	headers: { "Content-Type": imageFile.mimeType },
});
```

```plaintext
// Read text file
const file = await sandbox.readFile('/workspace/app.js');
console.log(file.content);

// Read and parse JSON
const configFile = await sandbox.readFile('/workspace/config.json');
const config = JSON.parse(configFile.content);

// Read binary file (v0.10.1 with `rpc` transport)
const imageFile = await sandbox.readFile('/workspace/image.png', { encoding: 'none' });
return new Response(imageFile.content, {
  headers: { 'Content-Type': imageFile.mimeType }
});
```

Note

For more details on the `rpc` transport please see the [Transport](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/sandbox/configuration/transport/) docs.

## Organize files

```js
// Create directories
await sandbox.mkdir("/workspace/src", { recursive: true });
await sandbox.mkdir("/workspace/tests", { recursive: true });

// Rename file
await sandbox.renameFile("/workspace/draft.txt", "/workspace/final.txt");

// Move file
await sandbox.moveFile("/tmp/download.txt", "/workspace/data.txt");

// Delete file
await sandbox.deleteFile("/workspace/temp.txt");
```

```plaintext
// Create directories
await sandbox.mkdir('/workspace/src', { recursive: true });
await sandbox.mkdir('/workspace/tests', { recursive: true });

// Rename file
await sandbox.renameFile('/workspace/draft.txt', '/workspace/final.txt');

// Move file
await sandbox.moveFile('/tmp/download.txt', '/workspace/data.txt');

// Delete file
await sandbox.deleteFile('/workspace/temp.txt');
```

## Batch operations

Write multiple files in parallel:

```js
const files = {
	"/workspace/src/app.js": 'console.log("app");',
	"/workspace/src/utils.js": 'console.log("utils");',
	"/workspace/README.md": "# My Project",
};

await Promise.all(
	Object.entries(files).map(([path, content]) =>
		sandbox.writeFile(path, content),
	),
);
```

```plaintext
const files = {
  '/workspace/src/app.js': 'console.log("app");',
  '/workspace/src/utils.js': 'console.log("utils");',
  '/workspace/README.md': '# My Project'
};

await Promise.all(
  Object.entries(files).map(([path, content]) =>
    sandbox.writeFile(path, content)
  )
);
```

## Check if file exists

```js
const result = await sandbox.exists("/workspace/config.json");
if (!result.exists) {
	// Create default config
	await sandbox.writeFile("/workspace/config.json", "{}");
}

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

// Also available on sessions
const sessionResult = await session.exists("/workspace/temp.txt");
```

```plaintext
const result = await sandbox.exists('/workspace/config.json');
if (!result.exists) {
  // Create default config
  await sandbox.writeFile('/workspace/config.json', '{}');
}

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

// Also available on sessions
const sessionResult = await session.exists('/workspace/temp.txt');
```

## Best practices

* **Use `/workspace`** \- Default working directory for app files
* **Use absolute paths** \- Always use full paths like `/workspace/file.txt`
* **Batch operations** \- Use `Promise.all()` for multiple independent file writes
* **Create parent directories** \- Use `recursive: true` when creating nested paths
* **Handle errors** \- Check for `FILE_NOT_FOUND` errors gracefully

## Troubleshooting

### Directory doesn't exist

Create parent directories first:

```js
// Create directory, then write file
await sandbox.mkdir("/workspace/data", { recursive: true });
await sandbox.writeFile("/workspace/data/file.txt", content);
```

```plaintext
// Create directory, then write file
await sandbox.mkdir('/workspace/data', { recursive: true });
await sandbox.writeFile('/workspace/data/file.txt', content);
```

### Binary file encoding

Use `encoding: "none"` (with `rpc` transport) for binary files:

```js
// Write binary
await sandbox.writeFile("/workspace/image.png", readableStream);

// Read binary
const file = await sandbox.readFile("/workspace/image.png", {
	encoding: "none",
});
```

```plaintext
// Write binary
await sandbox.writeFile('/workspace/image.png', readableStream);

// Read binary
const file = await sandbox.readFile('/workspace/image.png', {
  encoding: 'none'
});
```

For older SDK versions or `http` transport:

```js
// Write binary
await sandbox.writeFile("/workspace/image.png", base64data, {
	encoding: "base64",
});

// Read binary
const file = await sandbox.readFile("/workspace/image.png", {
	encoding: "base64",
});
```

```plaintext
// Write binary
await sandbox.writeFile('/workspace/image.png', base64data, { encoding: "base64" });

// Read binary
const file = await sandbox.readFile('/workspace/image.png', {
  encoding: 'base64'
});
```

### Base64 validation errors

When writing with `encoding: 'base64'`, content must contain only valid base64 characters:

```js
try {
	// Invalid: contains invalid base64 characters
	await sandbox.writeFile("/workspace/data.bin", "invalid!@#$", {
		encoding: "base64",
	});
} catch (error) {
	if (error.code === "VALIDATION_FAILED") {
		// Content contains invalid base64 characters
		console.error("Invalid base64 content");
	}
}
```

```plaintext
try {
  // Invalid: contains invalid base64 characters
  await sandbox.writeFile('/workspace/data.bin', 'invalid!@#$', {
    encoding: 'base64'
  });
} catch (error) {
  if (error.code === 'VALIDATION_FAILED') {
    // Content contains invalid base64 characters
    console.error('Invalid base64 content');
  }
}
```

## Related resources

* [Files API reference](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/sandbox/api/files/) \- Complete method documentation
* [Execute commands guide](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/sandbox/guides/execute-commands/) \- Run file operations with commands
* [Git workflows guide](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/sandbox/guides/git-workflows/) \- Clone and manage repositories
* [Code Interpreter guide](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/sandbox/guides/code-execution/) \- Generate and execute code files

Was this helpful?

YesNo

## On this page

[![](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/guides/manage-files/#page","headline":"Manage files · Cloudflare Sandbox SDK docs","description":"Read, write, organize, and synchronize files in the sandbox.","url":"https://developers.cloudflare.com/sandbox/guides/manage-files/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```