Skip to Content
Sophon Docs
Sophon Node

File Access

Listing, reading, and writing files on a node, with the roots you configure, the caps that apply, and what gets refused.

A node can list, read, and write files on the machine it runs on, but only inside folders you name. Everything outside them is refused before it touches disk.

The filesystem.access scope is not granted when you approve a device. This is one of the escalations you opt into deliberately.

Configuring roots

File access is confined to a configured list of root folders. Out of the box that is the user's Desktop, Documents, and Downloads.

An empty roots list denies everything. It is not a wildcard, and it is not "unrestricted". It is the off switch. Setting it to an empty list is the way to keep the scope granted while turning file access off entirely.

Roots live under fileSystemRoots in the node's config file. Note the capital S, and see the configuration file, which also explains why the spelling matters more than it should.

Choose roots as narrowly as the work allows. A node that only needs to drop reports somewhere should have that one folder, not the whole Documents tree.

Since v2.2.0 the device's owner can also set the folders from the Dashboard, in the Folders panel of the device's Settings tab, with the Gateway and the node both on 2.2.0 or later. Folders managed there override fileSystemRoots until the list is handed back to the device, and they pass more checks: no whole drive, no home folder or folder above it, no hidden, app-data or system folders. See Device Settings & Confirmations.

Containment

A path is fully resolved before it is tested for containment, not after. That means:

  • ~ is expanded.
  • .. segments are collapsed, so a path cannot climb out of a root by walking upward.
  • Symlinks are followed to their final target, and it is the target that must be inside a root. A link sitting in an allowed folder but pointing somewhere else fails the check instead of escaping through it. Since v2.2.0 a link or junction anywhere in a path is resolved before the check, one link at a time, not only at the end of the path, and a write through a link to a file that does not exist yet is checked where the file would be created. A path that goes through more than 40 links is refused as a loop.
  • A ~/… path stays under the home folder even when the rest of it is itself an absolute path.

Containment is also tested on a folder boundary rather than a string prefix, so a root of /home/you/work does not accidentally permit /home/you/work-secrets.

On Linux the comparison is case-sensitive, matching the filesystem's own behaviour; on Windows and macOS it is not.

Always refused

Since v2.2.0 some paths are refused whatever roots are configured, both as roots and as requested paths:

RefusedExampleWhat to do instead
The node's own folder~/.sophon-node, directly or through a link or junction into itNothing: the node's token, logs and state are not reachable through file commands
Network (UNC) paths\server\share, //server/shareMap a drive letter, or copy the files locally
Device paths\?\C:\…, \.\…, \??\…Use the ordinary path
Windows segments with ~ followed by a digitthe 8.3 short name PROGRA~1, and also backup~1.txtUse the long name, or rename the file
NTFS stream names on Windowsnotes.txt:hiddenUse the file itself
A link to a network or device path, or a disk mounted as a folder inside a roota \?\Volume{…}\ targetRefused without being followed; the node never contacts that host

A root in fileSystemRoots of one of those kinds is dropped, and so is a Desktop or Documents folder redirected to a network share when the node uses the default roots. The node logs a warning naming each dropped root and why when it starts. When every root was dropped, file commands are refused with "Every folder configured for file access on this node was refused" instead of "No filesystem roots are configured".

The node's own folder is denied only through paths the node can resolve. A subst or mapped network drive letter, or a hard link to a file inside it, is not a link the node can see. Creating either needs a shell command, which asks on the device by default, or the user.

Limits

LimitValueApplies to
Read size512 KBfilesystem.read
Write size512 KBfilesystem.write
Listing length500 entriesfilesystem.list
Binary contentrefusedfilesystem.read
Directory targetsrefusedfilesystem.write

A listing that hits the cap comes back flagged as truncated rather than silently short. A read that finds binary content refuses rather than returning something the model would only mangle. These commands are for text.

The three commands

files.list → filesystem.list

Lists entries in a folder inside a configured root.

ParamTypeDefaultNotes
pathstringrequiredMust resolve inside a root

Returns the entries with their names, sizes, and modified times, plus a flag when the result was truncated at the cap.

files.read → filesystem.read

Reads a text file inside a configured root.

ParamTypeDefaultNotes
pathstringrequiredMust resolve inside a root

Rated Low risk. Refuses binary content, and refuses anything over the size cap rather than truncating it.

files.write → filesystem.write

Writes a text file inside a configured root.

ParamTypeDefaultNotes
pathstringrequiredMust resolve inside a root
contentstringrequiredSubject to the size cap

Rated High risk, so it raises an approval — once, before anything is written, and delivered to the channel the conversation is actually in rather than only to the Dashboard.

Refuses a directory as its target. It also does not create folders: the parent has to exist already and be inside a root, and that parent is checked separately from the path being written, so a new file cannot be dropped just outside one.

One caveat on "always": in an interactive chat turn, approving a High-risk desktop action can cover further High-risk actions on that machine for the rest of the run, so a second write inside that window may not ask again. That standing consent lasts thirty minutes, belongs to one conversation, is cleared by a Gateway restart, and never extends to a workflow, a scheduled run, a webhook or an MCP call — those ask every time. See plan-level consent.

What this is not

There is no file transfer between the Gateway and a node. These commands read and write in place, on the machine, and the content travels as part of the command result like any other. Moving a large file between machines is not something a node does.

Files on the Sophon server itself are a different thing entirely, reached with different tools. files.* means the user's machine.

Where to go next