Filesystem

Filesystem entries expose directory-backed or read-only embedded storage to runtime modules. This page is a configuration reference; its YAML blocks are individual entry fragments rather than complete projects.

Entry Kinds

Kind	Description
`fs.directory`	Directory-based filesystem
`fs.embed`	Read-only embedded filesystem

Directory Filesystem

- name: uploads
  kind: fs.directory
  directory: "/var/data/uploads"
  auto_init: true
  mode: "0755"

Field	Type	Default	Description
`directory`	string	required	Root path
`auto_init`	bool	false	Create directory if missing
`mode`	string	0755	Unix permission mode (octal)
`link_policy`	string	`contained`	Symbolic-link policy: `contained` or `owner_safe`
`base`	string	-	Relative-path base: `project` (process working directory) or `module` (owning module load root)

Absolute paths are used as given, whatever base says.

For a relative path, base: project keeps it relative to the process working directory. Both base: module and an unset base resolve it against the load root of the module that owns the entry, looked up through the entry's registry owner. When the entry has no owning module, or that module has no resolvable resource root, the path stays relative to the process working directory.

Any other value is rejected with invalid directory base.

The mode restricts all file operations. Execute bits are added automatically when all read bits are set and no execute bit is.

With the default contained policy, operations stay inside the configured root directory.

On Unix, owner_safe also permits reads through links to external regular files when the target and every canonical parent are owned by the process UID or root and are not group- or other-writable. Policy refusals return permission errors, including from exists(). Writes, removals, renames, and directory traversal remain contained; removing a link changes the link itself. On Windows and other unsupported systems, owner_safe behaves as contained.

Embedded Filesystem

- name: static
  kind: fs.embed

Embedded filesystems load from pack resources using the entry ID. They are read-only.

Embedded filesystems are used internally and normally do not require manual configuration.

Operations

Both filesystem types implement:

Operation	Directory	Embed
Open/Read	Yes	Yes
Stat	Yes	Yes
Lstat	Yes	Yes
ReadDir	Yes	Yes
OpenFile (write)	Yes	No
Remove	Yes	No
Mkdir	Yes	No
Rename	Yes	No

Write operations on embedded filesystems return an error.

Lua API

See Filesystem Module for file operations.