Banata

Core Concepts

File System

Learn how to use /workspace, when to read files directly, when to use artifacts, and how checkpoints, documents, and recordings fit into file workflows.

The file system is the memory of a sandbox.

The most important path is:

text
/workspace

That is where your workflow should usually place:

  • downloaded inputs
  • generated reports
  • transformed documents
  • intermediate files another step needs later

Why /workspace matters

If your workflow spans more than one step, /workspace is what ties those steps together.

For example:

  • the agent can browse a site and save notes to /workspace/research.md
  • a later step can convert that report to PDF
  • your app can read the file or download it as an artifact

Read, write, and list files

Write:

ts
await sandbox.fs.write("/workspace/report.txt", "hello");

Read:

ts
const content = await sandbox.fs.read("/workspace/report.txt");

List:

ts
const entries = await sandbox.fs.list("/workspace");

When to read a file directly

Direct reads are best when:

  • the file is small
  • you want the contents immediately
  • the file is mostly internal workflow output

When to use artifacts instead

Artifacts are for outputs you want to treat as durable deliverables.

Common examples:

  • PDFs
  • packaged workspace outputs
  • checkpoint-related files
  • browser recordings

Read artifact state:

ts
const state = await sandbox.getArtifacts();

Create a download URL:

ts
const download = await sandbox.getArtifactDownloadUrl("artifact-key");
console.log(download.url);

Checkpoints

A checkpoint is a saved restore point for the sandbox.

ts
const checkpoint = await sandbox.checkpoint();
const checkpoints = await sandbox.listCheckpoints();
await sandbox.restoreCheckpoint(checkpoints[0].id);

Use checkpoints when:

  • a workflow is long
  • you want a recovery point before a risky step
  • a human will step in and you want an easy restore target

Document conversion

Document tools let the sandbox convert files as part of the workflow.

ts
await sandbox.convertDocument("/workspace/report.html", {
  format: "pdf",
});

Recordings

When browser recording is enabled, the recording is saved as an artifact.

That is useful for:

  • audit trails
  • QA review
  • support and debugging

Recommended output strategy

For most agent workflows:

  1. let the agent write working files into /workspace
  2. inspect the directory with fs.list()
  3. read small files directly with fs.read()
  4. convert or package final outputs
  5. use artifacts for durable downloads

Related pages