Modal sandbox: evaluate native filesystem APIs and clarify overwrite compatibility

[Filimoa]

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:

Operation	Current shell writes	Native write_bytes
Write through a symlink	Updates the target	Replaces the symlink; target remains unchanged
Overwrite a hard-linked file	Updates contents visible through both links	Replaces the destination inode; other links retain old contents
Overwrite an existing 0640 file	Preserves permissions	Resulting permissions were 0644

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:

Modal version	Median write: shell → native	Median read: shell → native
1.4.3	0.459s → 0.407s	0.342s → 0.328s
1.5.4	0.690s → 0.528s	0.584s → 0.511s

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.

[Ayushraj06-bit]

A couple of code-level data points that might help scope the decision.

The abstract write() contract in src/agents/sandbox/session/base_sandbox_session.py only specifies path resolution and the user parameter; it says nothing about overwrite semantics. Looking at what providers actually do on main:

• Native provider upload APIs (semantics owned by the provider, not the SDK): e2b (files.write), Daytona (fs.upload_file), Runloop (file.upload), Vercel (write_files), Blaxel (fs.write_binary), Cloudflare (HTTP PUT file/<path>).
• Shell transport, in-place: Docker (cat > path, or a staged file plus cp) and Modal (cat > path).
• Local: unix_local opens with O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW in _unix_local_file_ops.py, so it truncates regular files in place but refuses to write through a symlink at all.

So "preserve in-place writes" is not a cross-provider guarantee today. It is an incidental property of two shell transports, and the SDK's own reference provider already deliberately breaks the symlink-follow case. That makes this a Modal-local question rather than an SDK-wide contract change, which I think narrows it.

Given the bar set in #4567, the remaining question is whether a concrete workload sees the ~15-160 ms per-op savings in the table above as material. If not, documenting that Modal transfers are shell-based and closing seems reasonable. If it is, the smallest reversible step is native read behind a stat-size guard with fallback to cat above Modal's documented limit, leaving write on cat > untouched, since read has no overwrite semantics to argue about.

Would maintainers be open to that narrow native-read step as a first PR, or is the preference to keep Modal transfers shell-based and document it? Happy to implement whichever direction is chosen.