golem-add-initial-files

name	golem-add-initial-files
description	Adding initial files to Golem agent filesystems via the `files:` section in `golem.yaml`. Use when provisioning local or remote files into an agent's virtual filesystem, setting read-only / read-write permissions, or configuring file mounts at the component, agent, template, or preset level.

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 → components → agents → 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.

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: {}
        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: {}
        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: {}
        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: {}
        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:

Target Path	Source	Level
/etc/ssl/certs/ca-certificates.pem	./shared/ca-certificates.pem	componentTemplates.shared
/data/schema.sql	./data/schema.sql	components.my-ns:my-component
/data/seed.sql	./data/debug-seed.sql	components.my-ns:my-component.presets.debug
/etc/agent/config/*	./agent-config/ (directory)	agents.MyAgent
/etc/agent/config/overrides.toml	./agent-config/debug-overrides.toml	agents.MyAgent.presets.debug

Merge Modes

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

Mode	Behavior
append	(default) Add this level's files after the parent's files
prepend	Add this level's files before the parent's files
replace	Discard all parent files, use only this level's files

Example: Replace all inherited files

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

Example: Prepend files (higher priority positioning)

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 — identical files across agent types are stored only once in the registry and shared via hardlinks on the executor node.
• Files are downloaded lazily by the worker executor when the agent is first started, then cached locally for subsequent starts.
• There is a configurable disk space limit for cached initial files on each executor node.
• 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.

Summary of All Methods

Method	Scope	Where
componentTemplates.*.files	All components using the template	golem.yaml
components.*.files	Single component, all its agents	golem.yaml
agents.*.files	Single agent type	golem.yaml
*.presets.*.files	Component or agent preset	golem.yaml
filesMergeMode	Controls merge at any level	golem.yaml