Files

There are two ways to move files, depending on whether you need text staging or byte-exact transfer.

Stage files with files

The files field on an exec request writes files into the guest before the command runs. This is the simplest way to drop a script or test fixtures:

{
  "files": [
    { "path": "solve.py", "content": "print(6 * 7)" },
    { "path": "tests/test_solve.py", "content": "from solve import *\n" }
  ],
  "command": "python -m pytest -q"
}

files writes text (UTF-8) and appends a trailing newline to content that lacks one. Paths may be relative to the working dir or absolute; parent directories are created as needed.

Byte-exact IO with the Python SDK

For binary payloads — or any transfer where a trailing newline would corrupt the content — the collimate-rl Sandbox moves bytes exactly over the same exec channel, with no wire change and end-to-end sha256 verification.

from collimate_rl import Sandbox, connect

client = connect()   # reads COLLIMATE_API_KEY
with Sandbox("python", client=client) as sb:
    sb.upload_bytes("/work/model.bin", model_weights)   # exact bytes in
    sb.exec(command="cd /work && python run.py")
    out = sb.download("/work/result.parquet")           # exact bytes out

• upload_bytes(path, data) streams base64 chunks into a temp file, verifies size + sha256 in-guest, then atomically moves it into place — a failed or partial upload never leaves a truncated file.
• download(path) reads the file back with a sha256 checked end-to-end, so a corrupted or truncated transfer raises instead of returning bad bytes.

Transfer limits

One exec's output is capped in the guest at 16 MiB, and base64 inflates 4/3, so a single download tops out around 11 MiB. For larger artifacts, split the file or stage it to object storage the sandbox can reach (see per-fork egress).

Reading files back the raw way

Without the SDK you can always read a file in an exec — just be aware output is capped and merged stdout/stderr can interleave, which is exactly why the SDK frames and checksums its transfers:

{ "command": "cat /work/result.json" }

Next steps

• Running code — the full exec request.
• Templates — bake large, static assets into the image instead of uploading them per sandbox.