File transfer

File transfer should be explicit. A narrow copy operation is easier to audit and reason about than a broad writable host mount.

Copy into the guest

cargo run -- machine cp ./input.json filebox:/work/input.json
cargo run -- machine exec filebox -- python /work/process.py /work/input.json

machine cp is an advanced verb: it works, but it is hidden from machine --help.

Copy out of the guest

cargo run -- machine cp filebox:/work/output.json ./output.json

Use host mounts only when the workflow is intentionally a development workflow and the mounted path is narrow. A guest mount path has to sit under /data or /work; /mnt is refused because the runtime’s own config and secret drives live there.

Planned runtime SDK shape

Status: Planned lifecycle API.

Python

sandbox.files.write("/work/input.json", input_bytes)
result = sandbox.exec(["python", "/work/process.py"])
output = sandbox.files.read("/work/output.json")

TypeScript

await sandbox.files.write("/work/input.json", inputBytes);
const result = await sandbox.exec(["node", "/work/process.js"]);
const output = await sandbox.files.read("/work/output.json");

Security checklist

• Validate guest paths; reject traversal such as ../.
• Treat symlinks carefully when reading from the guest.
• Avoid mounting $HOME, credential directories, SSH agents, or cloud config paths.
• Treat snapshots as containing any files that existed in the guest at snapshot time.