Expose per-mount cache policy and metadata timeouts in the SDK and CLI

Author: zfy0701Created Sep 10, 2026Updated Sep 12, 2026
LabelsSDKFilesystemsCLI

Host-side edits to bind-mounted files can take several seconds to become fully visible inside a running sandbox. Could the SDK and CLI expose the existing filesystem cache controls per mount, so callers can choose freshness versus performance?

Existing support

microsandbox-filesystem already supports cache_policy, entry_timeout, and attr_timeout. However, the runtime uses their defaults when constructing directory mounts, and the Node SDK MountBuilder does not expose them.

Checked at commit fa3e43902e9bc49e1d85cc0a7298e13fe2374026 (v0.6.18):

Observed behavior

Tested microsandbox 0.6.17 on Linux, with Node v24.21.0 in the guest and an ordinary read-only directory bind mount. The reads below used the bind mount directly, without going through a guest-created OverlayFS mount.

  1. On the host, create sample.txt containing host-old (8 bytes, no newline), and bind its directory at /shared.
  2. In the guest, read /shared/sample.txt using fs.readFileSync(path, 'utf8').
  3. On the host, overwrite the same inode with host-longer-value (17 bytes).
  4. In the guest, repeat readFileSync every 200 ms, reopening the file on each read.

The guest initially returned host-lon, then returned the complete host-longer-value after approximately 5.1 seconds. This appears consistent with the default 5-second attribute timeout retaining the old file size. This is an observation from one run, not a guaranteed refresh interval.

Requested behavior

Expose the existing controls through per-mount SDK and CLI configuration:

Control Current default Desired opt-in setting for frequently changing host files
entry_timeout 5 seconds 0
attr_timeout 5 seconds 0
cache_policy Auto Never

Preserve existing defaults, carry the selected options through saved sandbox configuration and stop/start, and document the extra host I/O cost of disabling caches. Per-mount settings would let shared source directories prioritize freshness while stable dependency caches retain caching.

The requested values have not yet been tested in a patched runtime. Coherence of host changes beneath a mounted guest OverlayFS is a separate concern; exposing these controls should not imply that such a layout becomes supported.

Source: superradcompany/microsandbox