File System Access API
The File System Access API lets selected web apps work with user-chosen files and directories, creating a browser boundary for agents, editors, audit trails, and local data risk.
Definition
The File System Access API is a browser capability for web applications that need to interact with user-selected files and directories outside ordinary upload and download flows. The WICG draft says the API extends file-system APIs so developers can build web apps that interact with files on a user's local device, adding surfaces for modifying files and directories.
MDN describes the broader File System API as allowing interaction with files on a user's local device or user-accessible network file system, with core functions for reading, saving, writing, and directory access. Chrome's documentation frames the File System Access API around web apps such as IDEs, photo and video editors, and text editors.
Mechanism
The main picker entry points are showOpenFilePicker(), showSaveFilePicker(), and showDirectoryPicker(). The WICG draft calls them local file system handle factories. Chrome says window.showOpenFilePicker() displays a file picker and returns file handles after user selection. The same documentation says powerful picker methods must run in a secure context and be called from a user gesture.
Once a handle exists, code works with FileSystemFileHandle and FileSystemDirectoryHandle objects rather than raw paths. MDN documents FileSystemHandle.requestPermission() for requesting read or read/write permissions and queryPermission() for checking permission state. The WICG draft notes that "local" file system access may be cloud-backed, not only a physical disk.
Agent Context
For AI Browsers and Computer Use, this API marks a hard authority boundary. A browser agent that can read a file, edit a directory, or save over an existing document is no longer merely looking at web content. It is acting on a user's workspace, source tree, contract folder, medical export, tax record, slide deck, photo archive, or research notes.
The useful cases are real. A local-first coding assistant can open a project. A web editor can save a text file without a fake download loop. A data-cleaning tool can process a user-selected folder. The risk is equally real: a fluent agent can over-read files, overwrite evidence, leak directory names, write malicious project files, or make a user believe a broad handle was narrow.
Governance Use
Governance should treat file handles as delegated authority, not incidental UI state. A review record should preserve origin, top-level site, picker type, user activation, selected handle kind, requested mode, permission state, safe file or directory name, operation type, write destination, and whether a model or deterministic script initiated the action. Logs should avoid file contents unless there is an explicit evidence purpose and retention rule.
Agent platforms should separate read, propose, write, and delete. Reading a document to summarize it is not permission to rewrite it. Creating a new file is not permission to modify an existing file. Selecting one folder for export is not permission to crawl a home directory. The policy boundary should be visible before use.
Limits
Pickers and permission prompts are necessary but not sufficient. They do not explain legal privilege, trade secrets, intellectual property, family photos, union records, health files, or source-code signing risk. A user may approve a file picker to complete a task without intending to give a remote model a durable copy of the file or a reusable map of the directory.
The API also does not prove agent trustworthiness. A page can have a legitimate file handle and still make a bad decision. The safer pattern is narrow selection, mode separation, local processing where possible, visible diffs before writes, explicit delete confirmation, revocable permissions, and durable audit trails for agent-initiated file activity.
Review Record
- Selection: origin, top-level site, picker method, user activation, selected file or directory kind, and whether multiple selection was enabled.
- Permission: requested read or read/write mode, permission state, prompting path, revocation path, and frame or policy constraints.
- Operation: open, read, enumerate, create, overwrite, save as, delete, move, or export, with destination and timing.
- Agent trail: model instruction, tool call, proposed diff, human approval, rejected action, and retention rule for any copied content.
Source Discipline
Claims about picker methods, local file system handle factories, and cloud-backed "local" file systems should cite the WICG draft. Claims about handles, directory structure, and permission methods should cite MDN. Claims about secure contexts, user gestures, practical editor use cases, and direct reading or saving should cite Chrome's developer documentation. Claims about workplace policy, audit trails, or agent misuse are governance inferences from those technical surfaces.
Spiralist Reading
Spiralism reads file access as the place where the browser stops being a viewing machine and becomes a clerk at the edge of the personal archive. A file picker looks humble, but it is a ritual of delegation: this folder, this document, this save, this overwrite. Agentic browsers need that ritual to stay legible. Otherwise the machine that promises to help with work quietly becomes the authority that can rearrange the evidence of work.
Related Pages
- AI Browsers and Computer Use
- AI Agent Sandboxing
- AI Audit Trails
- Permissions Policy
- Permissions API
- Screen Capture API
- Local Font Access API
- WebUSB API
- Data Minimization
- Contextual Integrity
- The Operating System Becomes the AI Gatekeeper
Sources
- WICG, File System Access, specification draft.
- MDN Web Docs, File System API.
- MDN Web Docs, FileSystemHandle.
- MDN Web Docs, FileSystemHandle: requestPermission() method.
- MDN Web Docs, FileSystemHandle: queryPermission() method.
- Chrome for Developers, The File System Access API: simplifying access to local files.