golemcloud/golem/golem-edit-manifest

Editing the Golem Application Manifest (golem.yaml)

The golem.yaml file in the project root is the Golem Application Manifest. It defines the entire application: components, agents, build steps, environments, HTTP/MCP deployments, and more.

Manifest version: The manifestVersion field at the top of the file identifies the application manifest document version. Do not change it.

Top-Level Structure

manifestVersion: "1.5.0"          # Manifest document version — do not change
app: my-app                       # Application name
 
includes:                          # (optional) Glob patterns for additional manifest fragments
  - "components/*/golem.yaml"
 
componentTemplates:                # Reusable property layers (build, env, plugins, files)
  <template-name>: { ... }
 
components:                        # Component definitions by name (namespace:name)
  <ns:name>: { ... }
 
tools:                             # Canonical tool implementation declarations
  <tool-name>: { ... }
 
agents:                            # Agent type definitions by PascalCase name
  <AgentName>: { ... }
 
environments:                      # Deployment environments (local, cloud, custom)
  <env-name>: { ... }
 
version:                           # (optional) Logical version attached to each deployment
  git: { ... }                     #   git: | env: <VAR> | "1.2.3" (literal)
 
httpApi:                           # HTTP API domain deployments
  deployments: { ... }
 
mcp:                               # MCP (Model Context Protocol) deployments
  deployments: { ... }
 
bridge:                            # Bridge SDK generation configuration
  ts: { ... }
  rust: { ... }
 
customCommands:                    # User-defined CLI commands
  <command-name>: [...]
 
clean:                             # Extra paths for `golem clean`
  - "path/to/clean"
 
secretDefaults:                    # Secret defaults per environment
  <env-name>: {...}
 
retryPolicyDefaults:               # Retry policy defaults per environment
  <env-name>: {...}
 
resourceDefaults:                  # Quota resource defaults per environment
  <env-name>: {...}

Components

Components are keyed by namespace:name (e.g., my-app:billing).

components:
  my-app:billing:
    dir: billing                   # Base directory (relative to golem.yaml). Use "." for single-component apps ("module" for Go)
    templates:                     # Parent template names (inherit build, env, plugins, files)
      - rust
    componentWasm: target/wasm32-wasip2/debug/billing.wasm   # Path to built WASM
    outputWasm: golem-temp/billing.wasm                       # Path to final output WASM
    build:                         # Build commands (see Build Commands below)
      - command: cargo build --target wasm32-wasip2
    env:                           # Environment variables
      LOG_LEVEL: info
    tools:                         # Owner authorization; inherited by the component's agents
      search: {}
    plugins:                       # Plugin installations
      - name: otlp-exporter
        version: "0.1.0"
    files:                         # Initial filesystem entries
      - sourcePath: ./data/config.json
        targetPath: /etc/config.json
    clean:                         # Extra clean paths
      - target/
    presets:                       # Named presets with overrides
      debug:
        default: true
        env:
          LOG_LEVEL: debug
      release:
        env:
          LOG_LEVEL: warn

Key component fields

Component Templates

Templates define reusable property layers. Components reference them via templates:.

componentTemplates:
  my-rust:
    templates: [rust]              # Inherits the built-in "rust" template (build, guestLanguage)
    env:
      RUST_LOG: info
 
components:
  my-app:service:
    templates: [my-rust]           # Inherits from "my-rust" and, through it, from "rust"
    dir: service

Templates support the same fields as components except dir. Templates can themselves reference other templates via templates:, but a template may be inherited only through a single path: using two templates that both inherit the same template (e.g. templates: [my-ts, ts-extra] where both inherit ts) is rejected. The same applies to the templates lists of agents and tools. The built-in templates (rust, ts, effect, scala and moonbit) are provided by the CLI; don't define templates with these names.

Templates can declare the guest language of the components built with them via guestLanguage (ts, effect, rust, scala, moonbit or go). The built-in templates declare it, so templates inheriting them don't need to. A custom template that builds a component on its own (without inheriting a built-in template) should declare it, otherwise language-specific CLI features (dependency checks, bridge generation, REPL) are unavailable for its components. The templates applied to a component must not declare different languages.

Agents

Agent types are keyed by PascalCase name. They support the same cascading property fields as components (env, plugins, files, config, wasiConfig) but NOT build-related fields. Agents can also inherit from templates via templates:.

agents:
  MyAgent:
    templates: [shared-runtime]    # Inherit env/plugins/files from a template
    env:
      CACHE_TTL: "300"
    plugins:
      - name: otlp-exporter
        version: "0.1.0"
    files:
      - sourcePath: ./agent-data/model.bin
        targetPath: /data/model.bin
    presets:
      debug:
        default: true
        env:
          CACHE_TTL: "60"

Initial permission cards

Use initialCard on a component or agent, with lowerBound and upperBound containing positive and negative permission-string lists. Tool bindings expose tools but do not grant runtime permission. This fragment assumes the agent already has a Git binding; add its required filesystem permissions separately:

agents:
  RepositoryAgent:
    initialCard:
      lowerBound:
        positive:
          - "tool(?component/git) @ ?agent : invoke : status --cwd=/workspace/**"
        negative:
          - "tool(?component/git) @ ?agent : invoke : status --short --null"
      upperBound:
        positive:
          - "tool(?component/git) @ ?agent : invoke : status --cwd=/workspace/**"
        negative: []

Use primary command and long-option names in manifests and permission shares. Short aliases require effective metadata and are rejected at these context-free boundaries. Runtime derivation resolves aliases before attenuation and freezes their meaning durably.

Tool command paths match exactly. . means the root command, and whole-resource * means any invocation; an empty resource is not an alternative. Flags are unordered requirements, positionals are ordered prefixes, and extra arguments do not defeat a match. Thus status allows that command with arguments, not only an empty argument list. Denying status --short --null blocks both flags together even when reordered or accompanied by extras.

Attach option values with =. Inside a value, * matches zero or more non-slash characters and ** can cross slashes. /workspace/** includes /workspace/project/src, but not /workspace without its slash; matching does not normalize paths. Quote spaces (--message="two words") or empty values (--message=""), and backslash-escape literal stars. Preserve those escapes through YAML or JSON encoding.

Repeated options retain every occurrence. A positive --include=/workspace/** requires one matching value, not an all-values allowlist; use a negative --include=/private/** to block any matching private value. Repeating a positive requirement in a ceiling does not change this rule. Count requirements retain multiplicity. Opaque streams cannot satisfy restricted positive value patterns and cannot evade a potentially matching denial; authorization never drains streams. Derivation must narrow positives and retain or strengthen denials on both bounds.

Config and WASI Config

The config field accepts arbitrary YAML values (objects, arrays, scalars) passed as typed configuration to the agent at runtime. The wasiConfig field is a string-to-string map of WASI-level configuration variables.

components:
  my-app:service:
    config:
      model: gpt-4o-mini
      temperature: 0.2
      features:
        - summarize
        - translate
    wasiConfig:
      WASI_FLAG: enabled
 
agents:
  MyAgent:
    config:
      max_retries: 3
    wasiConfig:
      AGENT_WASI_OPT: "true"

Both fields follow the cascade hierarchy and support merge modes (wasiConfigMergeMode for wasiConfig).

Cascade / Merge System

Properties cascade from general to specific:

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

Each level can override or merge with its parent using merge modes:

Presets apply within their owning layer, not after all other layers. Golem resolves the base component, including its template and component presets, before it applies agent overrides and agent presets.

Component tool bindings authorize fresh component owners (including tools-only MCP calls) and default into real agents exported by that component. An agent-only binding does not authorize a fresh component owner. To opt an agent out of an inherited tool, remove it explicitly:

components:
  my-app:service:
    tools:
      search: {}
 
agents:
  RestrictedAgent:
    toolsMergeMode: remove
    tools:
      search: {}

When agents should not receive the defaults, prefer a separate component with no agents as the tool owner.

Presets