Agent Filesystem

Each agent runs in a sandboxed filesystem. Both the / path and the current working directory of an agent point to the root of this sandboxed filesystem. There is no way for an agent to access files outside its own filesystem.

Accessing the filesystem

TypeScript

For TypeScript agents, use node:fs or node:fs/promises to work with files.

In Golem 1.5, the QuickJS runtime provides a comprehensive filesystem API, so standard operations such as reading, writing, checking existence, creating directories, and listing directories are available.

Effect TypeScript

Effect TypeScript agents use node:fs or node:fs/promises, just like other TypeScript agents. The Effect template’s QuickJS runtime provides these filesystem implementations.

Rust

For Rust agents, use the standard std::fs module to work with files.

Golem Rust agents compile to WASI, so standard filesystem operations such as read_to_string, read, write, and read_dir work out of the box.

Scala

For Scala agents, use node:fs via Scala.js JavaScript interop.

Standard JVM file I/O APIs such as java.io.File and java.nio.file.* are not available in Scala.js. Define a small @JSImport("node:fs", JSImport.Namespace) facade and access it lazily at runtime.

MoonBit

For MoonBit agents, add "golemcloud/golem_sdk/filesystem" @fs to the import block in your component’s moon.pkg.

Its async helpers include read_bytes, write_bytes, and list_directory. Obtain the root directory descriptor with @fs.get_root_dir() and handle its optional result before passing the descriptor to these helpers.

Initial File System

The Initial File System (IFS) refers to all files that are present in the agent filesystem before the agent is started. These can include configuration files, static assets and other things that you want to include with your agent.

The IFS is configured on the level of a component, meaning that all agents created from a given component + version will always start with the same filesystem. To configure the IFS, include a files section in your golem.yaml

If you are using profiles in your golem.yaml, you currently have to include the files section in each of your profiles when overriding.


components:
  example:filesystem:
    template: ts
    files:
    - sourcePath: ./files/foo.txt
      targetPath: /foobar.txt
      permissions: read-write
    - sourcePath: ./files/bar.txt
      targetPath: /bar.txt
      permissions: read-only

After deploying the component, any new agents created will have the file /foobar.txt (and ./foobar.txt as the agent’s initial current directory is the root) available to them. The file /bar.txt on the other hand is only available for reading. Trying to open the file for writing will fail with a language-dependent error.

Updating an agent

Updating an agent that uses IFS requires some special consideration depending on the update mode you choose:

Automatic updates: The new code replays the old agent invocations on the files of the old revision. The replay starts from the files of its baseline, for example the initial files of the old revision, or the files that a snapshot-assisted update restores from the selected snapshot. The replay must produce exactly the same results and side effects as before. After the replay, at the update point, Golem applies the initial files of the new revision. The update fails when the new revision changes the declaration of an initial file at a path where the agent wrote, changed or deleted a file. See Automatic update.
Manual updates: On an executor with filesystem snapshots, Golem saves the agent’s files with the update snapshot and restores them in the target revision before golem:api/load-snapshot runs. The update fails when the target revision changes the declaration of an initial file at a path where the agent wrote, changed or deleted a file. See Manual updates. On other executors, a snapshot-based update works only while the agent’s files are its initial files. Otherwise the update fails, and the agent stays on its current revision. See Availability.

Files after a restart

Golem rebuilds the agent filesystem at each start. A full replay of the oplog runs the agent’s code again, and the code writes its files again. A start from a snapshot record replays only the entries after the record. On an executor with filesystem snapshots, Golem restores the files of the record before the replay. On other executors, Golem writes a snapshot record only while the agent’s files are its initial files, and a start from the record puts the initial files in place. An agent whose files changed takes no snapshot, so its start uses an older snapshot record or replays the full oplog, and the code writes its files again.

Externally accessing agent files

To serve files without writing a download method, use live filesystem mappings on a durable agent’s mount. They support streaming, HEAD, and single byte-range requests, including files created during initialization or overwritten by later invocations. For deployment-provisioned read-only assets, use immutable router files.

If a download needs application logic rather than direct file serving, define a code-first HTTP endpoint or a streaming router handler.