How to download files from a sandbox

On Runtime, you can take files out of a sandbox even after its work is paused. A paused sandbox keeps its whole disk. Keeping a sandbox paused costs $0.08 per decimal GB of saved state per month. Leaving a 2 vCPU, 4 GiB sandbox running idle costs $0.03125 an hour (pricing, checked 26 October 2026).

Read one file

TypeScriptimport { Sandbox } from "withruntime";await using sbx = await Sandbox.create();await sbx.files.write("/workspace/out/report.csv", "name,score\nada,9\n");const text = await sbx.files.readText("/workspace/out/report.csv"); // a stringconst bytes = await sbx.files.read("/workspace/out/report.csv"); // raw bytesconsole.log(text, bytes.length);console.log(await sbx.files.stat("/workspace/out/report.csv"));

Pythonfrom withruntime import Sandboxwith Sandbox.create() as sbx:    sbx.files.write("/workspace/out/report.csv", "name,score\nada,9\n")    text = sbx.files.read_text("/workspace/out/report.csv")  # str    data = sbx.files.read("/workspace/out/report.csv")  # bytes    print(text, len(data))    print(sbx.files.stat("/workspace/out/report.csv"))

Use read for images, archives and anything else that is not text. It returns the bytes unchanged.

Download a folder

TypeScriptimport { mkdtemp } from "node:fs/promises";import { tmpdir } from "node:os";import { join } from "node:path";import { Sandbox } from "withruntime";await using sbx = await Sandbox.create();await sbx.files.write("/workspace/results/summary.txt", "all tests passed\n");await sbx.files.write("/workspace/results/logs/run.log", "ok\n");const local = await mkdtemp(join(tmpdir(), "results-"));await sbx.files.download("/workspace/results", join(local, "results"));

Pythonimport pathlibimport tempfilefrom withruntime import Sandboxwith Sandbox.create() as sbx:    sbx.files.write("/workspace/results/summary.txt", "all tests passed\n")    local = pathlib.Path(tempfile.mkdtemp()) / "results"    sbx.files.download("/workspace/results", str(local))    print(sorted(p.name for p in local.rglob("*")))

The folder travels as one compressed archive, and each file keeps its permissions. From a terminal, cat prints a file. cp copies a file out when you pass <id>:/path as the source:

Terminalid=$(runtime sandboxes create)mkdir -p project && echo "print('hi')" > project/main.pyruntime sandboxes cp ./project "${id}:/workspace/project"runtime sandboxes cat "${id}" /workspace/project/main.pyruntime sandboxes cp "${id}:/workspace/project" ./project-copyruntime sandboxes stop "${id}"

Find what to download first

files.list walks a directory to a depth. files.glob matches a pattern. An agent can use them to collect every chart or report it made, without knowing the names:

TypeScriptimport { Sandbox } from "withruntime";await using sbx = await Sandbox.create();await sbx.files.write("/workspace/charts/a.png", "png bytes");for (const entry of await sbx.files.list("/workspace", { depth: 2 }))  console.log(entry.type, entry.size, entry.path);console.log(await sbx.files.glob("**/*.png"));

Ways out, compared

Reading a file costs nothing on its own. The sandbox is billed for measured CPU at $0.025 per active vCPU-hour, and for memory at $0.0075 per GiB-hour.

Mistakes to avoid

• Stopping before copying out. A stopped sandbox is not a backup. Download what you need first. Or keep the files on a volume, which outlives sandboxes and is backed up off its server every day (volume backups).
• Reading a large command output through exec. A plain result holds at most 64 KiB of stdout. Redirect the command to a file, and read the file.
• A relative path. Paths are absolute. /workspace is the sandbox user's home.
• Checking for a file by catching an error. files.exists(path) returns true or false. stat returns the type, size, mode and times.

Related

• Upload a folder, the other direction.
• Pause and resume a sandbox to keep results without paying for idle compute.
• Data analysis agent: charts and tables made in a sandbox, fetched back.
• Files in the Python reference.

Facts on this page were checked on 26 October 2026.