Modal sandbox: evaluate native filesystem APIs and clarify overwrite compatibility

Describe the feature

Consider adopting Modal's native sandbox.filesystem API for sandbox file transfers, with an explicit decision on overwrite compatibility. The Modal provider currently transfers files through shell commands. The native API could reduce transfer overhead, but live testing found behavior differences that prevent a straightforward replacement.

Observed compatibility differences

Tests against Modal 1.4.3 and 1.5.4 found:

Modal also documents a 5 GB read limit for its filesystem API. That needs consideration before replacing shell-based reads.

The investigation inspected Agents SDK v0.22.3, where shell transfers were still in use. Both tested Modal versions support the native APIs.

Preliminary performance results

Same-container measurements, retaining SDK path validation, with six alternating observations per method:

These are small-sample file-operation measurements, not sandbox startup measurements. Binary round trips exceeding 8 MiB also passed.

Decision requested

Would maintainers prefer to preserve the current in-place write semantics, or explicitly adopt replacement semantics for the Modal provider?

Before implementing this, it would help to establish:

• Whether the observed symlink, hard-link, and permission behavior is intentional and supported by Modal.
• Which overwrite semantics the Agents SDK intends to guarantee across providers.
• Whether native reads can be adopted independently without introducing a size-limit regression.

A stat-before-write fallback would need careful treatment: another sandbox process could change the destination between inspection and writing.

Any implementation should retain remote path validation, read-only grants, explicit-user access checks, SDK error categories, cancellation behavior, and avoid retrying ambiguous writes.

Modal's deprecation guidance concerns the older Sandbox.open/FileIO APIs; the SDK's existing shell-based transport is not using those deprecated APIs.

References: Modal filesystem API, migration guidance.

Start at the Modal provider's existing shell-based file-transfer entry point and review the reported compatibility measurements for symlinks, hard links, permissions, and the 5 GB read limit. Confirm the intended cross-provider overwrite semantics with maintainers before choosing an implementation. Done means an explicit compatibility decision and a plan that preserves the listed validation, access, error, cancellation, and retry behavior.