FileSystem API

fs exposes the computer’s sandboxed virtual filesystem.

Typical usage

fs.makeDir("/home/logs")
fs.write("/home/logs/boot.txt", "online")

if fs.exists("/home/logs/boot.txt") then
  print(fs.read("/home/logs/boot.txt"))
end

for _, name in ipairs(fs.list("/home")) do
  print(name)
end

-- Protect a scope and require auth for writes
fs.protect("/home/logs", "secret123", "write, delete")
print(fs.write("/home/logs/boot.txt", "denied until auth")) -- false

fs.auth("secret123")
print(fs.write("/home/logs/boot.txt", "allowed after auth")) -- true

fs.clearAuth()

Reference

  • list(path) Returns file/directory names in path.

  • makeDir(path) Creates a directory recursively. Returns true on success.

  • touch(path) Creates a file if missing and preserves existing file contents.

  • read(path) Reads a file and returns text content, or nil.

  • write(path, content) Writes UTF-8 text to a file, creating parent directories when needed.

  • delete(path) Deletes a file or an empty directory.

  • changeDir(path) Changes current working directory.

  • getCurrentDir() Returns current working directory (for example /home).

  • exists(path) Returns whether a path exists.

  • isDir(path) Returns whether a path is a directory.

  • normalizePath(path) Returns canonical virtual path (resolves ., .., and relative paths).

  • protect(path, password, [operations]) Adds or updates password protection for a path scope.

  • unprotect(path, password) Removes protection rule from a path when password matches.

  • auth(password) Unlocks all matching protected scopes for the current session.

  • clearAuth() Clears the current filesystem auth session.

  • listPermissions() Returns all configured protection rules with lock state.

  • getPermissions(path) Returns the effective protection rule for path, or none.

  • getLastError() Returns the last filesystem error (including permission-denied reason).

Notes

  • Paths are sandboxed to this computer’s virtual root.

  • Escaping the sandbox via traversal is blocked.

  • delete will not remove non-empty directories.

  • makeDir returns false when the path already exists.

  • Protection rules are path-scoped and inherited by child paths (longest matching scope wins).

  • Supported operation tokens: read, write, delete, list, all.

  • Aliases: copy (read+write), move (read + write + delete), paste (write), rw (read + write).

  • auth(password) unlocks matching scopes until clearAuth() or computer/session reset.

  • Protection metadata is persisted under /etc/.fs_permissions by the runtime.