Skip to main content
The filesystem API lets you list, read, write, move, and delete files inside the sandbox, plus upload tar archives in batch.

​
Path resolution

  • Absolute paths are used as-is.
  • Relative paths resolve from the server process working directory.
  • Requests that attempt to escape allowed roots are rejected by the server.

​
List entries

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

const entries = await sdk.listFsEntries({
  path: "./workspace",
});

console.log(entries);

​
Read and write files

PUT /v1/fs/file writes raw bytes. GET /v1/fs/file returns raw bytes. 
import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

await sdk.writeFsFile({ path: "./notes.txt" }, "hello");

const bytes = await sdk.readFsFile({ path: "./notes.txt" });
const text = new TextDecoder().decode(bytes);

console.log(text);

​
Create directories

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

await sdk.mkdirFs({ path: "./data" });

​
Move, delete, and stat

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

await sdk.moveFs({
  from: "./notes.txt",
  to: "./notes-old.txt",
  overwrite: true,
});

const stat = await sdk.statFs({ path: "./notes-old.txt" });
await sdk.deleteFsEntry({ path: "./notes-old.txt" });

console.log(stat);

​
Batch upload (tar)

Batch upload accepts application/x-tar and extracts into the destination directory. 
import { SandboxAgent } from "sandbox-agent";
import fs from "node:fs";
import path from "node:path";
import tar from "tar";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

const archivePath = path.join(process.cwd(), "skills.tar");
await tar.c({
  cwd: "./skills",
  file: archivePath,
}, ["."]);

const tarBuffer = await fs.promises.readFile(archivePath);
const result = await sdk.uploadFsBatch(tarBuffer, {
  path: "./skills",
});

console.log(result);