Add streaming read/write API for Sandbox

[scotttrinh]

This adds streaming file access to the unstable Sandbox filesystem API through box.fs.open. Both async and sync runtimes support reading and writing binary or text data without buffering entire files in memory. The implementation includes bounded-memory tar/gzip encoding for uploads, transfer validation, configurable timeouts and chunk sizes, and concrete file-handle types with familiar context-manager semantics.

async with sandbox.create_sandbox(
    name="streaming-files-demo",
    runtime="python3.13",
) as box:
    async with (
        await anyio.open_file("input.bin", "rb") as local,
        box.fs.open("workspace/input.bin", "wb") as remote,
    ):
        while chunk := await local.read(64 * 1024):
            await remote.write(chunk)

    async with (
        box.fs.open("workspace/input.bin", "rb") as remote,
        await anyio.open_file("output.bin", "wb") as local,
    ):
        while chunk := await remote.read(64 * 1024):
            await local.write(chunk)

---

Note: since we currently must know the full size of the file before sending the data to the backend, we spool the contents to a TemporaryFile, read the size, and then stream the data from that temp file to the backend. If you know the size of the content, you can skip this spooling by providing the exact byte size in open(..., size=byte_size) which will stream directly to the server. We hope this requirement will go away soon, so we're mostly documenting the size-less API for now.

---

Edit:

When looking at the implementation and anticipating what we'll need when adding Blob into the mix here, I decided that this work should also add an iter_coroutine style byte streaming utility. transport.py now supports incrementally produced request bodies and owned streaming responses.

A new session-owned byte-stream "runtime" normalizes various byte sources behind one internal interface. It also provides disk-backed temporary byte files (using tempfile.TemporaryFile for sync sessions and anyio.TemporaryFile for async sessions) for workflows that need seeking, size discovery, or mutation without buffering the complete object in memory which we'll also need in our upcoming Blob redesign.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vercel-py	Ready	Preview	Jun 25, 2026 3:32pm

[Copilot]

Pull request overview

This PR adds a streaming file I/O API to the unstable Sandbox filesystem via box.fs.open(...), enabling chunked reads/writes for binary and text data (async + sync), and switches uploads to a bounded-memory tar+gzip streaming encoder with transfer validation and configurable request timeouts.

Changes:

• Introduces concrete streaming file-handle types (async + sync) with context-manager semantics and open() overloads.
• Implements streaming tar+gzip archive generation for uploads plus size/mode/chunk validation and new transfer-focused error types.
• Adds unit/live tests and updates unstable docs + example demonstrating streaming transfers.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unstable/test_sandbox_transfer_validation.py	Adds tests for transfer validation helpers, exported handle/error types, and timeout defaulting.
tests/unstable/test_sandbox_streaming_archive.py	Adds coverage for the bounded-memory tar+gzip encoder and async/sync archive iterators.
tests/unstable/test_sandbox_filesystem.py	Extends filesystem tests for streaming read/write behavior, response closing, and newline buffering.
tests/unstable/test_sandbox_api_client.py	Updates API client construction to include the new file-transfer timeout parameter.
tests/live/test_unstable_sandbox_live.py	Adds a live scenario test validating streaming upload/download parity across async/sync drivers.
tests/live/_unstable_scenarios.py	Implements streaming transfer scenario helpers using the new fs.open API.
src/vercel/unstable/sandbox/sync.py	Exposes new streaming handle types and transfer errors in the sync public unstable API.
src/vercel/unstable/sandbox/init.py	Exposes new streaming handle types and transfer errors in the async public unstable API.
src/vercel/unstable/README.md	Documents the new open() streaming API and provides examples.
src/vercel/_internal/unstable/sandbox/sync_runtime.py	Adds sync fs.open, switches reads to streamed responses, and writes to streamed archive uploads.
src/vercel/_internal/unstable/sandbox/sync_filesystem_handle.py	Implements sync streaming reader/writer handle classes and publish plumbing.
src/vercel/_internal/unstable/sandbox/streaming_archive.py	Adds bounded-memory tar+gzip streaming encoder and async/sync body generators with size checks.
src/vercel/_internal/unstable/sandbox/service.py	Adds write_archive + open_read_response service methods and wires file-transfer timeouts into the API client.
src/vercel/_internal/unstable/sandbox/runtime_common.py	Introduces upload entry model + tar-path normalization and validation helpers for sizes/modes/chunks.
src/vercel/_internal/unstable/sandbox/options.py	Adds file_transfer_timeout to service options with a 5-minute default.
src/vercel/_internal/unstable/sandbox/filesystem_handle_common.py	Adds shared handle helpers (option validation, read-size validation, text codecs).
src/vercel/_internal/unstable/sandbox/errors.py	Adds transfer-focused filesystem error types (size mismatch, transfer base error).
src/vercel/_internal/unstable/sandbox/async_runtime.py	Adds async fs.open, switches reads to streamed responses, and writes to streamed archive uploads.
src/vercel/_internal/unstable/sandbox/async_filesystem_handle.py	Implements async streaming reader/writer handle classes and publish plumbing.
src/vercel/_internal/unstable/sandbox/api_client.py	Adds streamed read responses, streamed upload bodies, and request timeouts for file transfers.
examples/unstable/sandbox_06_streaming_files.py	Adds an end-to-end example demonstrating streaming upload and download.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.