elizaos--eliza/plugins/plugin-native-filesystem/README.md

@elizaos/plugin-native-filesystem

Mobile-safe filesystem bridge for the elizaOS runtime.

Adds a single DeviceFilesystemBridge service. Planner-visible read, write, and directory list operations are routed through the canonical FILE action with target=device:

• FILE with action=read, target=device — read a file from the user's device-files root.
• FILE with action=write, target=device — write a file to the user's device-files root.
• FILE with action=ls, target=device — list a directory inside the user's device-files root.

Backends

The bridge picks one of two backends at startup:

• Capacitor — when window.Capacitor.isNativePlatform() is true (iOS, Android). Uses @capacitor/filesystem with Directory.Documents as the root.
• Node — when not on Capacitor. Uses fs/promises rooted at resolveStateDir() + "/workspace" (default ~/.local/state/eliza/workspace unless XDG or env overrides it).

Both backends reject absolute paths, .. traversal, NUL bytes, and (on Node) any resolution that escapes the workspace root.

FILE integration

This package owns only the device filesystem bridge. It does not register planner-facing file actions. The @elizaos/plugin-coding-tools FILE action discovers the bridge by the device_filesystem service type and delegates target=device operations to it.

iOS Info.plist (apply in the host app)

For iOS users to see files written into Directory.Documents, the host app's Info.plist needs the following keys added:

<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

Without those keys, files still write — they just aren't browsable from the Files.app side. Add them in the host app's iOS shell, not in this package.

Android

No special manifest changes are required for Capacitor Directory.Documents (the Capacitor Filesystem plugin handles scoped storage and MediaStore on Android 10+). Cross-app sharing through MediaStore.Downloads belongs in the host app's AndroidManifest, not here.

Service type

DEVICE_FILESYSTEM_SERVICE_TYPE = "device_filesystem". Resolve programmatically with getDeviceFilesystemBridge(runtime).