Skip to main content
import { Sandbox } from '@declaw/sdk';
import type { EntryInfo, WriteInfo, WriteEntry, FilesystemEvent } from '@declaw/sdk';
sbx.files is the Filesystem instance available on every Sandbox. All paths must be absolute paths within the sandbox filesystem.

​
sbx.files.read()

Read a file’s content as a string. 
const content: string = await sbx.files.read('/home/user/script.py');
console.log(content);
​
path
string
required
Absolute path inside the sandbox.
​
opts.user
string
default:"'user'"
Unix user context for the read operation.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<string>

​
sbx.files.write()

Write content to a file, creating parent directories automatically. 
const info: WriteInfo = await sbx.files.write(
  '/home/user/hello.ts',
  'console.log("hello from sandbox");',
);
console.log(info.path, info.size);
​
path
string
required
Absolute destination path.
​
data
string | Uint8Array
required
Content to write. Accepts a string or a Uint8Array (decoded as UTF-8).
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<WriteInfo>

​
sbx.files.writeFiles()

Write multiple files in a single batch request. 
const results: WriteInfo[] = await sbx.files.writeFiles([
  { path: '/home/user/main.ts', data: 'console.log("main")' },
  { path: '/home/user/data.json', data: '{"key": "value"}' },
]);
​
files
WriteEntry[]
required
Array of WriteEntry objects. Each has path (string) and data (string or Uint8Array).
​
opts.user
string
default:"'user'"
Unix user context applied to all files.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<WriteInfo[]>

​
sbx.files.list()

List entries in a directory. 
const entries: EntryInfo[] = await sbx.files.list('/home/user', { depth: 2 });
for (const entry of entries) {
  console.log(entry.type, entry.path, entry.size);
}
​
path
string
required
Absolute path to the directory.
​
opts.depth
number
default:"1"
Recursion depth. 1 lists only immediate children.
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<EntryInfo[]>

​
sbx.files.exists()

Check whether a path exists. 
const exists: boolean = await sbx.files.exists('/home/user/output.csv');
if (exists) {
  const csv = await sbx.files.read('/home/user/output.csv');
}
​
path
string
required
Absolute path to check.
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<boolean>

​
sbx.files.getInfo()

Get metadata about a file or directory. 
const info: EntryInfo = await sbx.files.getInfo('/home/user/script.py');
console.log(info.name, info.type, info.size);
​
path
string
required
Absolute path to query.
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<EntryInfo>

​
sbx.files.remove()

Remove a file or directory. 
await sbx.files.remove('/home/user/temp.txt');
​
path
string
required
Absolute path to remove.
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<void>

​
sbx.files.rename()

Rename or move a file or directory. 
const moved: EntryInfo = await sbx.files.rename(
  '/home/user/draft.ts',
  '/home/user/final.ts',
);
​
oldPath
string
required
Current absolute path.
​
newPath
string
required
New absolute path. Can be in a different directory (move semantics).
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<EntryInfo> for the renamed entry.

​
sbx.files.makeDir()

Create a directory (including parent directories if needed). 
const created: boolean = await sbx.files.makeDir('/home/user/output/results');
​
path
string
required
Absolute path of the directory to create.
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<boolean> — true if the directory was created.

​
sbx.files.watchDir()

Watch a directory for filesystem change events. 
const handle = await sbx.files.watchDir('/home/user/data', {
  recursive: true,
});
​
path
string
required
Absolute path of the directory to watch.
​
opts.user
string
default:"'user'"
Unix user context.
​
opts.recursive
boolean
default:"false"
Whether to watch subdirectories recursively.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<WatchHandle>

​
Data models

​
EntryInfo

interface EntryInfo {
  name: string;    // Filename or directory name
  path: string;    // Full absolute path
  type: FileType;  // 'file' or 'dir'
  size: number;    // Size in bytes (0 for directories)
}

​
FileType

enum FileType {
  File = 'file',
  Dir  = 'dir',
}

​
WriteInfo

interface WriteInfo {
  path: string;  // Absolute path of the written file
  size: number;  // Bytes written
}

​
WriteEntry

interface WriteEntry {
  path: string;            // Absolute destination path
  data: string | Uint8Array; // Content to write
}

​
FilesystemEvent

interface FilesystemEvent {
  type: FilesystemEventType;
  path: string;
  timestamp?: number;
}

​
FilesystemEventType

enum FilesystemEventType {
  Create = 'create',
  Write  = 'write',
  Remove = 'remove',
  Rename = 'rename',
  Chmod  = 'chmod',
}

​
WatchHandle

class WatchHandle {
  /** Stop accepting new events. Idempotent. */
  stop(): void;

  /** Drain and return all events buffered since the last call. */
  getNewEvents(): FilesystemEvent[];
}
The handle uses a poll-and-drain model — call getNewEvents() to pull buffered events. There is no async iterator or callback subscription.

​
Examples

​
Upload and run a script

await sbx.files.write('/home/user/analyze.ts', `
  const data = [1, 2, 3, 4, 5];
  const sum = data.reduce((a, b) => a + b, 0);
  console.log('Sum:', sum);
`);

const result = await sbx.commands.run('npx ts-node /home/user/analyze.ts');
console.log(result.stdout);

​
Batch upload a dataset

import { readFileSync, readdirSync } from 'fs';

const entries = readdirSync('./dataset').map((name) => ({
  path: `/data/${name}`,
  data: readFileSync(`./dataset/${name}`),
}));

await sbx.files.writeFiles(entries);

​
Download generated output

await sbx.commands.run("node -e \"require('fs').writeFileSync('/tmp/out.csv','a,b\\n1,2')\"");
const csv = await sbx.files.read('/tmp/out.csv');
console.log(csv); // "a,b\n1,2"

​
Check and create directories

const outputDir = '/home/user/results';
if (!(await sbx.files.exists(outputDir))) {
  await sbx.files.makeDir(outputDir);
}
await sbx.files.write(`${outputDir}/result.txt`, 'analysis complete');