Filesystem

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

string

required

Absolute path inside the sandbox.

string

default:"'user'"

Unix user context for the read operation.

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

string

required

Absolute destination path.

string | Uint8Array

required

Content to write. Accepts a string or a Uint8Array (decoded as UTF-8).

string

default:"'user'"

Unix user context.

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"}' },
]);

WriteEntry[]

required

Array of WriteEntry objects. Each has path (string) and data (string or Uint8Array).

string

default:"'user'"

Unix user context applied to all files.

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);
}

string

required

Absolute path to the directory.

number

default:"1"

Recursion depth. 1 lists only immediate children.

string

default:"'user'"

Unix user context.

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');
}

string

required

Absolute path to check.

string

default:"'user'"

Unix user context.

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

string

required

Absolute path to query.

string

default:"'user'"

Unix user context.

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');

string

required

Absolute path to remove.

string

default:"'user'"

Unix user context.

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',
);

string

required

Current absolute path.

string

required

New absolute path. Can be in a different directory (move semantics).

string

default:"'user'"

Unix user context.

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');

string

required

Absolute path of the directory to create.

string

default:"'user'"

Unix user context.

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,
});

string

required

Absolute path of the directory to watch.

string

default:"'user'"

Unix user context.

boolean

default:"false"

Whether to watch subdirectories recursively.

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');

Python SDK

TypeScript SDK

Go SDK

`sbx.files.read()`

`sbx.files.write()`

`sbx.files.writeFiles()`

`sbx.files.list()`

`sbx.files.exists()`

`sbx.files.getInfo()`

`sbx.files.remove()`

`sbx.files.rename()`

`sbx.files.makeDir()`

`sbx.files.watchDir()`

Data models

`EntryInfo`

`FileType`

`WriteInfo`

`WriteEntry`

`FilesystemEvent`

`FilesystemEventType`

`WatchHandle`

Examples

Upload and run a script

Batch upload a dataset

Download generated output

Check and create directories

​sbx.files.read()

​sbx.files.write()

​sbx.files.writeFiles()

​sbx.files.list()

​sbx.files.exists()

​sbx.files.getInfo()

​sbx.files.remove()

​sbx.files.rename()

​sbx.files.makeDir()

​sbx.files.watchDir()

​Data models

​EntryInfo

​FileType

​WriteInfo

​WriteEntry

​FilesystemEvent

​FilesystemEventType

​WatchHandle

​Examples

​Upload and run a script

​Batch upload a dataset

​Download generated output

​Check and create directories

`sbx.files.read()`

`sbx.files.write()`

`sbx.files.writeFiles()`

`sbx.files.list()`

`sbx.files.exists()`

`sbx.files.getInfo()`

`sbx.files.remove()`

`sbx.files.rename()`

`sbx.files.makeDir()`

`sbx.files.watchDir()`

Data models

`EntryInfo`

`FileType`

`WriteInfo`

`WriteEntry`

`FilesystemEvent`

`FilesystemEventType`

`WatchHandle`

Examples

Upload and run a script

Batch upload a dataset

Download generated output

Check and create directories