Files

The workspace

/work          ← the agent's working directory
├── payments/  ← a repository, cloned into /work/<repo name>
├── uploads/   ← your files
└── out/       ← what the agent leaves for you

• The session's disk holds 5 GiB and is mounted at /work in every sandbox the session runs in.
• Each repository is cloned into /work/<repo name>. See Repositories and patches.
• Put your files in uploads/. The agent is told to leave what you ask for in out/.
• A path in a file call is relative to /work: uploads/photo.png, out/report.md, payments/README.md.

You don't need to explain this to the agent. When its sandbox starts, LatentStack writes a note into its instructions with this layout, how files move, what a pause keeps and what the network allows. Your own instructions come after the note and win where the two meet.

Upload a file

import { readFile } from "node:fs/promises"

const photo = await readFile("photo.png")
const file = await sessions.uploadFile(session.id, "uploads/photo.png", photo, { contentType: "image/png" })
console.log(file.path, file.size, file.sha256)

• The file is stored at that path. Missing folders are created, and an existing file is replaced.
• The answer is the stored file: { object: "agent.file", path, size, sha256 }.
• TypeScript takes a Blob or File, an ArrayBuffer, a typed array such as a Node.js Buffer, or a string. A string is the file's content, as UTF-8.
• Python takes bytes, an open binary file, or a path. A str is the path of a file to read, not content.
• One upload is at most 1 GiB. A larger file fails with file_too_large.

Show the agent an image

Name workspace images in files when you send a message. The model sees them together with your text.

await sessions.message(session.id, "Make a 3-second mp4 that zooms into this photo. Save it as out/zoom.mp4.", {
  files: ["uploads/photo.png"],
})

• PNG, JPEG, GIF or WebP only. Up to 10 images per message, 5 MiB each and 20 MiB in all.
• Any other file, such as a CSV or a video, the agent reads at its path. Name the path in your message, not in files.

List and download

import { writeFile } from "node:fs/promises"
import { basename } from "node:path"

const { data } = await sessions.listFiles(session.id, { prefix: "out/" })
for (const file of data) {
  const blob = await sessions.downloadFile(session.id, file.path)
  await writeFile(basename(file.path), Buffer.from(await blob.arrayBuffer()))
}

• A listing is { object, data: [{ path, size, modified_at }], truncated }, in path order. .git folders are left out.
• prefix keeps only paths that start with it. limit is up to 1,000, the default. When truncated is true there were more files; narrow the prefix.
• A download is the whole file: a Blob in TypeScript, bytes in Python. Its content type comes from the file's extension.

Delete a file

await sessions.deleteFile(session.id, "uploads/photo.png")

A path with no file fails with not_found. You don't need to clean up before deleting a session: its disk goes with it.

Limits, and paused sessions

Over HTTP

To attach images over HTTP, list their paths in the message input's files.