Upload and download files

Most agent workflows need more than a code string. You can upload inputs, let the sandbox transform them, and download generated files when the task is done.

Prerequisites

• Completed the Quickstart.
• RUNRA_API_KEY set in your environment.

1. Create a sandbox

import { Sandbox } from "runra";

const sbx = await Sandbox.create({ timeout: 600 });

2. Upload an input file

Use files.write() to create files inside the sandbox:

const csv = `name,score
ada,98
grace,95
linus,91
`;

await sbx.files.write("/home/user/scores.csv", csv);

You can also create directories with shell commands before writing nested files:

await sbx.commands.run("mkdir -p /home/user/workdir");
await sbx.files.write("/home/user/workdir/input.txt", "hello Runra\n");

3. Process the file in the sandbox

const execution = await sbx.runCode(`
import csv
from pathlib import Path

input_path = Path("/home/user/scores.csv")
output_path = Path("/home/user/summary.md")

rows = list(csv.DictReader(input_path.open()))
avg = sum(int(row["score"]) for row in rows) / len(rows)
best = max(rows, key=lambda row: int(row["score"]))

output_path.write_text(
    f"# Score summary\\n\\n"
    f"Average score: {avg:.1f}\\n\\n"
    f"Top scorer: {best['name']} ({best['score']})\\n"
)

print(output_path)
`);

console.log(execution.logs.stdout.join("\n"));

4. Download the generated file

const summary = await sbx.files.read("/home/user/summary.md");
console.log(summary);

Expected output:

# Score summary

Average score: 94.7

Top scorer: ada (98)

5. List files for debugging

const files = await sbx.files.list("/home/user");
console.log(files);

This is useful when an agent writes files to an unexpected path.

Complete example

import { Sandbox } from "runra";

const sbx = await Sandbox.create({ timeout: 600 });

try {
  await sbx.files.write(
    "/home/user/scores.csv",
    "name,score\nada,98\ngrace,95\nlinus,91\n"
  );

  await sbx.runCode(`
import csv
from pathlib import Path
rows = list(csv.DictReader(open("/home/user/scores.csv")))
avg = sum(int(row["score"]) for row in rows) / len(rows)
Path("/home/user/summary.txt").write_text(f"average={avg:.1f}\\n")
`);

  const summary = await sbx.files.read("/home/user/summary.txt");
  console.log(summary);
} finally {
  await sbx.kill();
}

Notes

• Use /home/user as the default working area for agent-generated files.
• Prefer text formats such as JSON, CSV, Markdown, and source files for simple agent workflows.
• For large binary artifacts, write them to object storage from inside the sandbox or expose a short-lived download URL from your application.
• Always clean up temporary sandboxes with kill().