Editing the Golem Application Manifest (golem.yaml)

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:
  my-app:billing:
    dir: billing                   # Base directory (relative to golem.yaml). Use "." for single-component apps
    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

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

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"

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"

componentTemplates → components → agents → presets

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

components:
  my-app:service:
    presets:
      debug:
        default: true               # Selected by default
        env:
          LOG_LEVEL: debug
      release:
        env:
          LOG_LEVEL: warn

build:
  - command: cargo build --target wasm32-wasip2
    dir: .                         # Optional working directory
    env:                           # Optional extra env vars
      RUSTFLAGS: "-C opt-level=2"
    rmdirs: [target/old]           # Directories to delete before running (runs before mkdirs)
    mkdirs: [target/new]           # Directories to create before running (runs after rmdirs)
    sources: ["src/**/*.rs"]       # Inputs for up-to-date checks
    targets: ["target/wasm32-wasip2/debug/*.wasm"]  # Outputs for up-to-date checks

build:
  - generateQuickjsCrate: golem-temp/quickjs-crate   # Generate QuickJS Rust crate
    wit: wit
    jsModules: { "main.js": "esm" }
    world: my-world                                    # Optional WIT world
 
  - generateQuickjsDts: golem-temp/bindings.d.ts      # Generate TypeScript declarations
    wit: wit
 
  - injectToPrebuiltQuickjs: golem-temp/quickjs.wasm  # Inject JS into prebuilt QuickJS
    module: dist/bundle.js
    into: golem-temp/output.wasm
 
  - preinitializeJs: golem-temp/output.wasm            # Pre-initialize JS runtime
    into: golem-temp/preinit.wasm

customCommands:
  test:
    - command: cargo test --target wasm32-wasip2
      dir: .
  lint:
    - command: cargo clippy --target wasm32-wasip2

environments:
  local:
    default: true                  # First environment is default if not specified
    server: local                  # Built-in local server
    cli:
      format: text
      autoConfirm: true
  cloud:
    server: cloud                  # Golem Cloud
  staging:
    server:                        # Custom server
      url: https://staging.example.com
      auth:
        oauth2: true               # or: staticToken: "my-token"
      workerUrl: https://staging-workers.example.com   # Optional separate worker URL
      allowInsecure: false         # Optional, allow insecure connections
    componentPresets: [release]    # Preset names to activate
    cli:
      format: json
      redeployAgents: true         # Delete and recreate agents; agent state is lost
    deployment:
      compatibilityCheck: true
      versionCheck: true
      securityOverrides: false

# OAuth2 (interactive login)
auth:
  oauth2: true
 
# Static token
auth:
  staticToken: "my-secret-token"

version:                           # application-wide default
  git:
    tagPattern: "v*"               # required for git tag mode; "*" = all tags
    hashFallback: true             # untagged repo → short commit hash
    staticFallback: "v0.0.0"       # no git / not a repo → this value
 
environments:
  local:
    version:
      git:
        allowDirty: true           # partial override; inherits the rest from the root

httpApi:
  deployments:
    local:
      - subdomain: my-app  # resolves to my-app.localhost:9006 by default
        webhookUrl: /webhooks/                     # Optional webhook path prefix
        agents:
          TaskAgent: {}                             # No auth
          SecureAgent:
            securityScheme: my-oidc                 # OIDC security scheme name
          DevAgent:
            testSessionHeaderName: X-Test-Auth      # Test auth header
    cloud:
      - subdomain: my-app  # resolves to my-app.apps.golem.cloud
        agents:
          TaskAgent: {}
          SecureAgent:
            securityScheme: prod-google-oidc

components:
  my-app:search-implementation:
    componentWasm: build/search-implementation.wasm
  my-app:tool-owner:
    componentWasm: build/tool-owner.wasm
    tools:
      search: {}
 
tools:
  search:
    component: my-app:search-implementation
 
mcp:
  deployments:
    local:
      - subdomain: my-mcp  # resolves to my-mcp.localhost:9007 by default
        tools:
          search:
            ownerComponent: my-app:tool-owner
            include: [query]

bridge:
  ts:
    external:
      agents: "*"                    # Generate for all agents
      outputDir: ./bridge-sdk/ts     # Optional custom output directory
  rust:
    external:
      agents:
        - MyAgent                    # Agent type name
        - my-app:billing             # Component name (all agents in that component)
      outputDir: ./bridge-sdk/rust
      additionalDerives:
        - '^Order.*=PartialEq,Eq'
        - 'Response$=custom_derive::ApiType'
      additionalDependencies:
        anyhow: "1"
        custom_derive:
          path: ./crates/custom-derive   # Relative to this manifest file
          package: custom-derive-macros
          features: [api]
          defaultFeatures: false
        git_derive:
          git: https://github.com/example/derive-macros
          tag: v1.2.3                    # Use at most one of branch/tag/rev

golem generate-bridge --language rust \
  --derive-rule '^Order.*=PartialEq,Eq' \
  --rust-dependency 'custom_derive = { package = "custom-derive-macros", path = "./crates/custom-derive", features = ["api"], default-features = false }'

plugins:
  - name: otlp-exporter
    version: "0.1.0"
    account: golem                 # Optional account
    parameters:                    # Optional key-value config
      endpoint: http://localhost:4317
      protocol: grpc

files:
  - sourcePath: ./data/config.json       # Local path or URL
    targetPath: /etc/app/config.json      # Absolute path in agent filesystem
    permissions: read-only                # read-only (default) or read-write
  - sourcePath: ./static-assets/          # Directory — recursively included
    targetPath: /var/www/static/
  - sourcePath: https://example.com/model.bin   # Remote URL
    targetPath: /data/model.bin

env:
  API_KEY: "{{ MY_API_KEY }}"
  DB_URL: "prefix-{{ DB_HOST }}-suffix"

secretDefaults:
  local:
    apiKey: "test-key-123"
  prod:
    apiKey: "{{ PROD_API_KEY }}"

retryPolicyDefaults:
  local:
    default-retry:
      priority: 10
      predicate: "true"                    # Always match
      policy:
        countBox:
          maxRetries: 3
          inner:
            exponential:
              baseDelay: { secs: 1, nanos: 0 }
              factor: 2.0

resourceDefaults:
  local:
    api-calls:
      limit:
        type: Rate
        value: 100
        period: minute
        max: 1000
      enforcementAction: reject        # reject, throttle, or terminate
      unit: request
      units: requests
    storage:
      limit:
        type: Capacity
        value: 1073741824              # 1 GB
      enforcementAction: reject
      unit: byte
      units: bytes
    connections:
      limit:
        type: Concurrency
        value: 50
      enforcementAction: throttle
      unit: connection
      units: connections

components:
  my-app:new-service:
    dir: new-service
    templates: [rust]

agents:
  MyAgent:
    env:
      NEW_VAR: "value"

components:
  my-app:service:
    plugins:
      - name: my-plugin
        version: "1.0.0"
        parameters:
          key: value

environments:
  staging:
    server:
      url: https://staging.example.com
      auth:
        staticToken: "{{ STAGING_TOKEN }}"

httpApi:
  deployments:
    staging:
      - domain: api-staging.example.com
        scheme: https
        agents:
          MyAgent: {}

clean:
  - golem-temp/
  - dist/
 
components:
  my-app:web:
    clean:
      - node_modules/.cache/
      - build/