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.
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