Adding Initial Files to Golem Agent Filesystems

Initial files (IFS — Initial File System) provision files into an agent’s virtual filesystem when it starts. Files are defined in the application manifest (golem.yaml) and uploaded to the Golem registry during golem deploy. They follow the same cascade property system as environment variables.

File Entry Structure

Each file entry has three fields:

files:
  - sourcePath: ./data/config.json       # local path (relative to golem.yaml) or URL
    targetPath: /etc/app/config.json      # absolute path inside the agent filesystem
    permissions: read-only                # optional: read-only (default) or read-write

• sourcePath — the source of the file content. Can be:
  • A relative local path (resolved relative to the golem.yaml file location)
  • An absolute local path
  • An HTTP/HTTPS URL to download the file from a remote server
  • A local directory — all files in the directory are recursively included, preserving the directory structure under targetPath
• targetPath — the absolute path where the file appears inside the agent’s WASI filesystem. Must start with /.
• permissions — optional. Either read-only (default) or read-write.

Cascade Hierarchy (Most General → Most Specific)

componentTemplates (including their selected presets)
  → components (including their selected presets)
  → agents (including their selected presets)

Each level can define files (a list of file entries) and filesMergeMode (how to combine with the parent level). More specific levels are applied on top of less specific ones.

Presets apply within their owning layer. Golem resolves the base component, including its template and component presets, before applying agent overrides and agent presets.

1. Component Template Level

Define shared initial files for all components that use a template:

componentTemplates:
  my-template:
    files:
      - sourcePath: ./shared/defaults.conf
        targetPath: /etc/app/defaults.conf

All components referencing my-template via templates: [my-template] inherit these files.

2. Component Level

Define or add initial files for a specific component:

components:
  my-ns:my-component:
    templates: [my-template]
    files:
      - sourcePath: ./component-data/schema.sql
        targetPath: /data/schema.sql

By default, these files are appended to any files inherited from the template.

3. Agent Type Level

Define initial files for a specific agent type within a component:

agents:
  MyAgent:
    files:
      - sourcePath: ./agent-config/settings.toml
        targetPath: /etc/agent/settings.toml
        permissions: read-write

4. Preset Level (Component and Agent)

Both components and agents support presets that can add or override initial files. Presets are selected at build/deploy time.

Component preset:

components:
  my-ns:my-component:
    files:
      - sourcePath: ./data/base-config.json
        targetPath: /etc/app/config.json
    presets:
      debug:
        default: true
        files:
          - sourcePath: ./data/debug-config.json
            targetPath: /etc/app/debug.json

Agent preset:

agents:
  MyAgent:
    files:
      - sourcePath: ./agent-data/prod.env
        targetPath: /etc/agent/env
    presets:
      debug:
        default: true
        filesMergeMode: replace
        files:
          - sourcePath: ./agent-data/debug.env
            targetPath: /etc/agent/env

Complete Multi-Level Example

componentTemplates:
  shared:
    files:
      - sourcePath: ./shared/ca-certificates.pem
        targetPath: /etc/ssl/certs/ca-certificates.pem
 
components:
  my-ns:my-component:
    templates: [shared]
    files:
      - sourcePath: ./data/schema.sql
        targetPath: /data/schema.sql
    presets:
      debug:
        default: true
        files:
          - sourcePath: ./data/debug-seed.sql
            targetPath: /data/seed.sql
 
agents:
  MyAgent:
    files:
      - sourcePath: ./agent-config/
        targetPath: /etc/agent/config/
        permissions: read-write
    presets:
      debug:
        default: true
        files:
          - sourcePath: ./agent-config/debug-overrides.toml
            targetPath: /etc/agent/config/overrides.toml

With the debug preset, the final resolved files for MyAgent would include:

Merge Modes

By default, files from child levels are appended to the parent list. You can change this per level with filesMergeMode:

Example: Replace all inherited files

agents:
  MyAgent:
    filesMergeMode: replace
    files:
      - sourcePath: ./only-this-file.txt
        targetPath: /data/only-this.txt

prepend changes list order, not target priority. Duplicate target paths fail validation; use replace to discard inherited entries rather than adding another entry at the same target.

Example: Prepend files

agents:
  MyAgent:
    filesMergeMode: prepend
    files:
      - sourcePath: ./priority-config.json
        targetPath: /etc/priority.json

Source Types

Local files

Relative paths are resolved from the directory containing golem.yaml:

files:
  - sourcePath: ./data/config.json
    targetPath: /etc/app/config.json

Local directories

If sourcePath points to a directory, all files are included recursively. The directory structure is preserved under targetPath:

files:
  - sourcePath: ./static-assets/
    targetPath: /var/www/static/

For example, if ./static-assets/ contains index.html and css/style.css, the agent filesystem will have /var/www/static/index.html and /var/www/static/css/style.css.

Remote files (HTTP/HTTPS)

Download files from a URL at deploy time:

files:
  - sourcePath: https://example.com/data/model.bin
    targetPath: /data/model.bin

Remote sources are downloaded and hashed during golem deploy. Only single files are supported for remote sources (not directories).

File Permissions

Each file can be marked as read-only (default) or read-write:

files:
  - sourcePath: ./config.json
    targetPath: /etc/app/config.json
    permissions: read-only          # agent can only read this file
 
  - sourcePath: ./scratch/workspace
    targetPath: /tmp/workspace
    permissions: read-write         # agent can read and write this file

When a directory source is used, the permission setting applies to all files within that directory.

Important Notes

• Target paths must be unique — if two file entries resolve to the same target path, deployment fails with a validation error.
• Files are content-addressed. The executor populates agent filesystems by copying, cloning, or reflinking files as supported by the filesystem, not by sharing hardlinks.
• The worker executor downloads initial files when needed. Its weak-reference cache can reuse a file while a live cache entry retains it; it does not guarantee reuse across subsequent starts.
• The initial-file cache has no dedicated configurable disk-space cap.
• Initial files are not passed per agent instance at creation time via golem agent new. They are defined at the agent type level in the manifest and applied to all instances of that type.

Initial Files, Updates and Snapshots

• When an agent updates to a new component revision, Golem applies the initial files of the target revision at the update point. If the target revision changes the declaration of an initial file at a path where the agent wrote, changed or deleted a file, the update fails, and the agent stays on its current revision.
• On an executor without filesystem snapshots, Golem takes snapshots of an agent only while its files are exactly its initial files. A read-write initial file counts as a change, also when the agent does not write to it. Such an agent then takes no automatic snapshots and recovers by a replay, and a snapshot-based manual update fails with UPDATE_NEEDS_FILESYSTEM_SNAPSHOTS. Use read-only initial files where the agent does not need to write.

Summary of All Methods