Work with files and artifacts

Upload inputs before a run. After it finishes, read logs from the operation result and download generated files from its saved image.

Need	Interface	Persistence
Supply one input	`files={"/guest/path": local_or_bytes}`	Follows that operation and its save choice
Prepare reusable files	`apply_files()` or retained run	New image UUID
Read one saved file	`image.read()`	Returns bytes without guest compute
Download one saved file	`image.download()` or inspect REST API	Local file plus existing image
Download a directory	Inspect tar-archive REST endpoint	Local archive plus existing image

Generate and retrieve

Complete Set up access, then place this fragment inside the async main() from the Python quickstart, replacing its file-saving workflow. It uses the authenticated client created there and selects an image containing mkdir and cp. Use Generate and download a binary artifact for a complete program, fresh-project setup, and byte-integrity checks.

from pathlib import Path

image = await client.images.use("alpine:3.19", strict=True)
run = await image.run(
    shell="mkdir -p /out && cp /input.bin /out/result.bin",
    files={"/input.bin": b"\x00input\xff"},
    disposable=False,
    timeout=30,
)
if run.exit_code != 0 or run.uuid is None:
    raise RuntimeError("File generation failed or returned no saved image")

destination = Path("result.bin")
await run.download("/out/result.bin", destination)
if destination.read_bytes() != b"\x00input\xff":
    raise RuntimeError("Downloaded bytes differ from the input")
print(f"Downloaded and verified {destination}")

Expected output: Downloaded and verified result.bin. Use absolute guest paths. The SDK uploads local inputs before spawn and uses content hashes for server-side deduplication. The operation result image is required for post-execution inspection. A disposable result has uuid is None. Captured stdin, stdout, and stderr each default to 1 MiB and can be set up to 10 MiB with truncate_output_at; the cap applies to recorded streams, not stdin delivery. run.result.truncated is true when either stdout or stderr was truncated. Store large or binary output as a file and validate its size or digest after download. If an artifact read fails after a successful retained run, retry by the recorded image UUID before executing the producer again. Contact the Sandboxes team before a workload depends on specific upload, download, or image-size limits, or on deletion and retention guarantees for each data surface. Do not put credentials in uploaded inputs, logs, or a retained image. See Security and data handling and the file download reference.

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Platform Notices

Generate and retrieve

​Generate and retrieve

Generate and retrieve