Transfer files

sandbox.files uploads and reads files through the sandbox API. Use absolute paths inside the sandbox so the result does not depend on a command's working directory.

Upload a local file

Read a file on your machine and pass its contents to files.write:

import { readFile } from "node:fs/promises";
import { URL } from "node:url";
import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  const data = await readFile(new URL("./fixture.txt", import.meta.url));
  await sandbox.files.write("/tmp/fixture.txt", data);
  console.log("Uploaded fixture.txt");
} finally {
  await sandbox.kill();
}

Read a file

By default, files.read returns text:

import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  await sandbox.files.write("/tmp/message.txt", "hello from AgentBox");
  const message = await sandbox.files.read("/tmp/message.txt");
  console.log(message);
} finally {
  await sandbox.kill();
}

Download a file

For a binary file, request bytes and save them locally:

import { writeFile } from "node:fs/promises";
import { URL } from "node:url";
import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  await sandbox.files.write("/tmp/report.txt", "Report is ready");
  const report = await sandbox.files.read("/tmp/report.txt", {
    format: "bytes",
  });
  await writeFile(new URL("./report.txt", import.meta.url), report);
  console.log("Downloaded report.txt");
} finally {
  await sandbox.kill();
}

For several files, use writeFiles in JavaScript or write_files in Python. For a large directory tree, package the directory or build it into a template instead of issuing many small requests.

See the Filesystem reference for metadata, listing, and watch operations.