Skip to content

Files

Call What it does
PUT /v2/sandboxes/{id}/files Writes the request's bytes to a file as they come, of any size (Content-Length required), its folders made: the file whole when they all came, or as it was. With offset, they are written into it in place.
GET /v2/sandboxes/{id}/files Returns a file's bytes.
GET /v2/sandboxes/{id}/files/list Lists a directory's entries in path order, to a depth.
GET /v2/sandboxes/{id}/files/stat Returns what is at a path: a file, a directory or a link, or nothing (exists false).
POST /v2/sandboxes/{id}/files:rename Moves a file, a link or a directory; refused 409 when something is at its new path, unless overwrite. With sha256 or size, a file written in parts is put in place once whole: its writes ended, then only a file of that size with every byte written and whose bytes hash to it moves; refused 409 upload_incomplete or checksum_mismatch, nothing moved.
POST /v2/sandboxes/{id}/files:remove Removes a file, a link or a directory (recursive for one with contents). One missing is success, removed false.

A write takes the request's body as it comes, so a file of any size is one PUT with its Content-Length: the file is replaced whole once every byte came, or left as it was. To send a large file in parts at once, or to go on after a lost connection, write each part with offset to a new path, then rename that path over the file with the whole file's size and sha256: once every part's write ended, the rename moves only a file of that size with every byte written and whose bytes hash to it.

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const sandbox = await runtime.sandboxes.create({});try {  await runtime.sandboxes.write(sandbox.id, new TextEncoder().encode("a,b\n1,2\n"), { path: "/tmp/data/input.csv" });  await runtime.sandboxes.exec(sandbox.id, { cmd: "tail -n 1 /tmp/data/input.csv > /tmp/data/out.csv" });  const out = new TextDecoder().decode(await runtime.sandboxes.read(sandbox.id, { path: "/tmp/data/out.csv" }));  console.log(out); // 1,2  if (out.trim() !== "1,2") throw new Error(out);} finally {  await runtime.sandboxes.delete(sandbox.id);}

A listed folder gives each entry's type, size, mode and time. A sandbox's files last as long as the sandbox. To keep them after it is deleted, take a snapshot.

Updated .md

Give this to your agent#

Paste this into your coding agent:

Read https://withruntime.com/docs/files.md. Move this project's files into and out of Runtime sandboxes with the files calls; a write streams, so a file of any size is one call.

This page as Markdown: https://withruntime.com/docs/files.md

Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial