Documentation Index
Fetch the complete documentation index at: https://docs.simplesandbox.dev/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The SDK provides file operations for reading and writing both text and binary content inside sandboxes. All operations use absolute paths.
Size limits
- Max write size: 10 MB per file (enforced by SDK)
- For larger files, consider streaming from your app or hosting assets externally
Writing files
Text files
// Write JSON config
await sandbox.files.write(
"/app/config.json",
JSON.stringify({ enabled: true, port: 3000 })
);
// Write script
await sandbox.files.write(
"/tmp/script.sh",
"#!/bin/bash\necho 'Hello from sandbox'\n"
);
Binary files
Write binary data using ArrayBuffer or Uint8Array:
import { readFile } from "node:fs/promises";
// Upload a local image
const imageBytes = await readFile("./logo.png"); // Node Buffer
await sandbox.files.write("/tmp/logo.png", new Uint8Array(imageBytes));
// Write raw bytes
const data = new Uint8Array([0x89, 0x50, 0x4E, 0x47]);
await sandbox.files.write("/tmp/data.bin", data);
Reading files
Text files
// Read as UTF-8 string (default)
const config = await sandbox.files.read("/app/config.json");
const parsed = JSON.parse(config);
// Read logs
const logs = await sandbox.files.read("/tmp/server.log");
console.log(logs);
Binary files
// Read as ArrayBuffer
const buffer = await sandbox.files.read("/tmp/logo.png", {
encoding: "binary"
});
console.log((buffer as ArrayBuffer).byteLength);
// Convert to Uint8Array if needed
const bytes = new Uint8Array(buffer as ArrayBuffer);
Common patterns
Upload and process
// Upload data file
await sandbox.files.write("/data/input.csv", csvContent);
// Process it
await sandbox.exec("python process.py /data/input.csv > /data/output.json");
// Download result
const result = await sandbox.files.read("/data/output.json");
Generate and download
// Generate file inside sandbox
await sandbox.exec("convert input.png -resize 50% output.png");
// Download the result
const resized = await sandbox.files.read("/tmp/output.png", {
encoding: "binary"
});
Multi-file operations
// Write multiple files
await Promise.all([
sandbox.files.write("/app/index.js", jsCode),
sandbox.files.write("/app/package.json", packageJson),
sandbox.files.write("/app/.env", envVars)
]);
// Read multiple files
const [logs, config, output] = await Promise.all([
sandbox.files.read("/tmp/app.log"),
sandbox.files.read("/app/config.json"),
sandbox.files.read("/tmp/result.txt")
]);
Implementation details
- Files are transferred via base64 encoding over the exec API
- Large files are chunked automatically (100KB chunks)
- Absolute paths are required (e.g.,
/tmp/file.txt, not file.txt)
- The SDK uses
cat for reads and printf | base64 -d for writes
Error handling
try {
const content = await sandbox.files.read("/missing/file.txt");
} catch (error) {
console.error("File read failed:", error);
}
// Check if file exists first
const check = await sandbox.exec("test -f /app/config.json && echo exists || echo missing");
if (check.stdout.trim() === "exists") {
const content = await sandbox.files.read("/app/config.json");
}
Best practices
Always use absolute paths
File operations require absolute paths starting with /:
// ❌ Wrong - relative path
await sandbox.files.read("config.json");
// ✅ Correct - absolute path
await sandbox.files.read("/app/config.json");
Specify encoding for binary files
Always use encoding: "binary" when working with non-text files:
// Write binary
await sandbox.files.write("/tmp/image.png", new Uint8Array(imageData));
// Read binary - specify encoding
const buffer = await sandbox.files.read("/tmp/image.png", {
encoding: "binary"
});
Other best practices
- Check size limits: Ensure files are under 10 MB before writing
- Batch operations: Use
Promise.all() for multiple file operations
- Handle errors: Wrap file operations in try-catch blocks
- Clean up: Remove temporary files when done to save space
