stateless code sandbox

[samhita-alla]

Add flyte.sandbox.create() for containerized execution

This PR introduces a lightweight sandbox runtime for executing arbitrary code inside an ephemeral stateless container, along with improvements to file handling.

Sandbox execution API

flyte.sandbox.create() runs arbitrary Python code or shell commands inside a one-off Docker container.

The container is built on demand from the declared packages / system_packages, executed once, and discarded.

Supported execution modes

Auto-IO mode (default): minimal boilerplate

• Triggered when code is provided and auto_io=True
• Flyte auto-generates an argparse preamble
• Declared inputs become local variables
• Declared scalar outputs are written automatically to /var/outputs/
• No manual I/O handling required

sandbox = flyte.sandbox.create(
    name="double",
    code="result = x * 2",
    inputs={"x": int},
    outputs={"result": int},
)

result = await sandbox.run.aio(x=21)  # -> 42

Verbatim mode: full script control

• Triggered when code is provided and auto_io=False
• Script runs exactly as written
• No CLI args injected
• Script handles all I/O manually via /var/inputs/ and /var/outputs/

sandbox = flyte.sandbox.create(
    name="etl",
    code="""
import json, pathlib

data = json.loads(pathlib.Path("/var/inputs/payload").read_text())
pathlib.Path("/var/outputs/total").write_text(
    str(sum(data["values"]))
)
""",
    inputs={"payload": File},
    outputs={"total": int},
    auto_io=False,
)

Command mode: run arbitrary commands

• Triggered when command is provided
• Executes any binary, shell pipeline, or test runner

sandbox = flyte.sandbox.create(
    name="test-runner",
    command=["/bin/bash", "-c", pytest_cmd],
    arguments=["_", "/var/inputs/solution.py", "/var/inputs/tests.py"],
    inputs={"solution.py": File, "tests.py": File},
    outputs={"exit_code": str},
)

Execution

Call .run() on the returned sandbox to build the image and execute.

Container improvements (_container.py)

• Adds support for parsing File input from kwargs

Deterministic remote file paths (_file.py) - File.named_remote(name)

Creates a File reference whose remote path is derived deterministically from name. Unlike File.new_remote(), which generates a random path on each call, this method produces the same path for the same name within a task execution, making it safe across retries.

• First attempt uploads to the path
• Retries resolve to the identical location
• Avoids duplicate uploads

If extraction fails, it falls back to the run base directory.

file = File.named_remote("report.csv")

async with file.open("wb") as f:
    await f.write(b"...")

New error type

InvalidPackageError: Introduced to signal invalid or unavailable packages during sandbox image build.

[cosmicBboy]

🚀