Get files in and out of a sandbox¶

There is no file API. No sb.files.write(), no upload endpoint, no download URL. The sandbox has exactly one door — exec — and every file you move goes through it or through the sandbox's own network connection.

That is a real limitation and this page is the honest workaround, not a feature tour. Read the size limits first: they decide which of the three patterns you need.

Size limits, read this first¶

size = int(sb.run("stat -c %s /tmp/out.csv").stdout.strip())
if size > 32 * 1024 * 1024:
    raise RuntimeError(f"{size} bytes will be truncated — push it out instead")

Pattern 1 — write a small text file in¶

A quoted heredoc. <<'EOF' with the marker in quotes stops the shell expanding $variables and backticks inside your content, which matters when the content is code an LLM wrote.

from sistemo import Sandbox

SCRIPT = """
import json, sys
print(json.dumps({"argv": sys.argv[1:]}))
"""

with Sandbox(stack="python") as sb:
    sb.run(f"cat > /tmp/main.py <<'SISTEMO_EOF'\n{SCRIPT}\nSISTEMO_EOF")
    print(sb.run("python3 /tmp/main.py a b").stdout)

import { Sandbox } from "@sistemo/sdk";

const script = `console.log(JSON.stringify(process.argv.slice(2)));`;

const sb = await Sandbox.create({ stack: "node" });
try {
  await sb.run(`cat > /tmp/main.js <<'SISTEMO_EOF'\n${script}\nSISTEMO_EOF`);
  console.log((await sb.run("node /tmp/main.js a b")).stdout);
} finally {
  await sb.close();
}

Pattern 2 — base64 for anything you did not write¶

The only safe way to move arbitrary bytes through a shell. It costs ~33% more bytes and it never breaks on quotes, newlines, markers or binary.

import base64
from sistemo import Sandbox

data = open("model.bin", "rb").read()          # any bytes at all
b64 = base64.b64encode(data).decode()

with Sandbox() as sb:
    sb.run(f"echo '{b64}' | base64 -d > /tmp/model.bin")
    print(sb.run("ls -l /tmp/model.bin").stdout)

import base64
from sistemo import Sandbox

with Sandbox() as sb:
    sb.run("head -c 100000 /dev/urandom > /tmp/blob")

    # Guard the 32 MiB stdout cap: base64 inflates by ~4/3.
    size = int(sb.run("stat -c %s /tmp/blob").stdout.strip())
    assert size * 4 / 3 < 32 * 1024 * 1024, "too big — use the network pattern"

    b64 = sb.run("base64 -w0 /tmp/blob").stdout
    data = base64.b64decode(b64)
    print(len(data))

base64 -w0 matters: without it base64 wraps at 76 columns and you have to strip the newlines before decoding.

Pattern 3 — let the sandbox move it over the network¶

For anything above roughly a megabyte, do not push bytes through exec at all. Sandboxes have outbound internet access (that is how pip install works), so the fastest path in and out is the sandbox talking to your own storage directly.

from sistemo import Sandbox

with Sandbox(stack="python") as sb:
    # In: the sandbox pulls it.
    sb.run("curl -fsSL -o /tmp/input.csv 'https://example.com/presigned-get-url'", timeout=120)

    sb.run("python3 -c \"import csv;print(sum(1 for _ in open('/tmp/input.csv')))\"")

    # Out: the sandbox pushes it.
    sb.run("curl -fsS -T /tmp/result.parquet 'https://example.com/presigned-put-url'", timeout=120)

Use presigned URLs with a short expiry. A long-lived credential passed into a sandbox is a credential you have handed to the code you did not trust enough to run on your own machine — the whole reason you are here.

Pattern 4 — keep the files instead of moving them¶

If the same data is needed by run after run, stop copying it. Attach a volume once and it survives the sandbox being destroyed and recreated.

A volume appears in the guest as the next drive — /dev/vdb for the first data disk — and nothing mounts it for you. Every run that wants it mounts it first:

A volume can only be attached to a stopped machine, so it cannot be attached to a fresh Sandbox() — that one is already running when you get it. Create the machine, stop it, attach, start it: Persist data with volumes walks through it, and Volumes has the endpoints.

Once it is attached, mount and write in one command:

mkdir -p /mnt/data && mount /dev/vdb /mnt/data && echo 'run 1' >> /mnt/data/log.txt

⚠ Chain them with &&. As two separate commands, a failed mount is followed by a write that succeeds — onto the machine's own root disk under /mnt/data, which is thrown away with the machine. Nothing errors, and the data is gone. Destroy the machine, attach the same volume to a new one, mount again — log.txt is still there.

Choosing¶

Related¶

• Exec — the endpoint all of this runs through
• Persist data with volumes
• Long-running work