Golem Application Manifest Reference
JSON schema
For the application manifest format we also publish JSON schemas. The current version (1.6.0) is available here .
The JSON schema is intended to be used with editors and IDEs, to help with base validation and code completion.
Use the following YAML comments at the start of your golem.yaml documents to enable schema support:
# $schema: https://schema.golem.cloud/app/golem/1.6.0/golem.schema.jsonNote that on top of the above schema there are other checks performed by golem, see the field reference below for details.
Loading of Application Manifest documents
The Golem CLI commands that use Application Manifest start by searching for golem.yaml documents in the current and the parent directories. The outermost golem.yaml found this way is used as the root manifest document, then more manifests are searched based on its includes field.
After resolving relative paths in the documents they are merged, then component selection happens: this can be either explicit, by passing component names as positional arguments to the commands that accept them (e.g. golem build <COMPONENT_NAME>...), or implicit, in which case only components defined in the directory - including subdirectories - from where the Golem CLI was executed are used.
An Application Manifest can also be selected explicitly with --app-manifest-path (-A). This chooses the root manifest instead of searching parent directories; its includes are still resolved. Use --disable-app-manifest-discovery (-X) to run without manifest discovery.
Template variables and functions
The Application Manifest has some fields which are used as templates, these fields are marked as Templated in the field reference below. The templates are using minijinja , which is a minimal templating engine based on Jinja2 syntax.
Available template variables:
componentName(aliascomponent_name): the current component name.appRootDir: the absolute application root directory.golemTempDir: the absolute Golem temporary directory for this application.componentDir: the absolute effective component directory, including itsdiroverride.componentDirRel: the component directory relative to the application root, with/separators; empty for the root or a component outside it.cargoTarget: the Cargo target directory, resolved lazily using the application root in Cargo workspace mode, or the component directory otherwise.moonbitBuildPackagePath: the artifact path below_build/wasm/<profile>/build/. For a root package it is<application-name>.wasm(the part of the component name before:); for a subpackage it is<componentDirRel>/<last-directory-segment>.wasm.
Available naming related string transforming functions:
to_snake_caseto_kebab_caseto_lower_camel_caseto_pascal_caseto_shouty_kebab_caseto_shouty_snake_caseto_title_caseto_train_caseto_upper_camel_case
build:
- command: tool-name build {{ componentName | to_snake_case }}.wasmComponent-implemented tools
Declare component-implemented tools by their logical names in the top-level tools map. Each declaration configures how Golem provisions the implementation. Use component to select the implementing component when more than one component exports the same tool name, or release to select a published implementation.
Tools-only component
A component can implement tools without exporting an agent:
components:
support:search-tools:
componentWasm: build/search-tools.wasm
tools:
search:
config:
index: documentation
env:
LOG_LEVEL: infoComponent containing tools and agents
Declarations are matched to metadata discovered from the built components, so one component can provide both kinds of export:
components:
support:assistant:
componentWasm: build/assistant.wasm
agents:
SupportAgent: {}
tools:
search: {}In this example, build/assistant.wasm must export both SupportAgent and the search tool.
Component and agent bindings
Tool bindings select which deployed tools an owner can invoke and provide invocation parameters. A component binding authorizes fresh owners such as tools-only MCP calls and is also inherited as a default by real agents exported by that component. Agent bindings alone do not authorize a fresh component owner. Use the automatically selected app-env:<environment> agent preset to vary real-agent bindings by environment. Map merge modes are upsert (the default), replace, or remove; parameter maps use the same modes.
environments:
production:
server: cloud
components:
support:assistant:
tools:
search:
version: "1.0.0"
parameters:
index: documentation
limit: 20
agents:
SupportAgent:
presets:
app-env:production:
tools:
search:
parametersMergeMode: upsert
parameters:
limit: 5
RestrictedAgent:
toolsMergeMode: remove
tools:
search: {}RestrictedAgent opts out of the inherited search binding. If no agent should inherit a tool, prefer a separate agentless owner component rather than adding the binding to a component that exports agents.
For a component-implemented tool, version can be omitted to use the version discovered from the component. When specified, it must match that version. The optional account must be the account that owns the locally deployed implementing component.
Initial tool permissions
Bindings expose a tool; initialCard supplies runtime authority. Components and agents accept a card with lowerBound and upperBound, each containing positive and negative permission lists. For an agent with a bound Git tool:
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: []This tool-permission fragment permits status with a matching cwd, including additional flags, but rejects calls containing both short and null regardless of their order or other flags. It does not grant filesystem access; supply the separate resource permissions required by the tool. Initial cards must also fit the deployer’s delegable authority.
Use primary command and long-option names in manifests. Runtime derivation can resolve aliases against durably selected metadata, but initial-card validation has no such definition context. Values are attached with =; * and ** are anchored value globs, while an entire resource of * permits any command. Positive repeated-option constraints require a matching occurrence, not that all occurrences are allowed. See Tool permission patterns for quoting, positional prefixes, denials, and opaque streams.
Tool middleware
Tool middleware has its own namespace under tools.middleware, so middleware is reserved and cannot be used as a tool name. A declaration selects one locally discovered implementation, optionally using component to disambiguate it, or one published release. Configuration in the declaration is consumer-owned and is not copied from a publisher:
tools:
middleware:
audit:
component: acme:audit
config:
logLevel: info
path-policy:
release:
account: middleware@example.com
name: path-policy
version: "1.2.0"
config:
allowedPrefix: /documentsAs with tools, release: { releaseId: "..." } is the exact-ID alternative to the account, name, and version coordinates. A remote declaration causes deployment to reconcile an automatically managed grant for the selected environment. Administrators can manage grants independently with golem tool middleware grant create, list, get, delete, and restore. Release lifecycle commands are under golem tool middleware release. Consumers can read the granted middleware descriptor but not the publisher’s component identity, configuration, environment, files, or plugins.
Publish a local middleware from an environment deployment with toolMiddlewareReleases:
toolMiddlewareReleases:
production:
audit: {}Publication and lifecycle follow tool releases: publication is committed atomically with deployment, the environment’s deployment.versionCheck controls immutability, and removing an entry does not de-publish it. Existing deployment snapshots remain pinned when a release or grant changes.
Universal means schema-agnostic, not environment-wide: universal middleware preserves the tool shape and can be installed either for the whole environment or on selected tool bindings. The environment-wide list accepts only universal middleware; per-tool lists accept both universal and monomorphic middleware. Per-tool middleware can be added at the environment, component, and agent binding layers. Lists preserve order and duplicate occurrences; each occurrence may have separate parameters and filesystem access:
environments:
production:
server: cloud
tools:
middleware:
- name: audit
parameters: { channel: security }
- name: audit
parameters: { channel: operations }
search:
middleware:
- name: path-policy
filesystemAccess: denied
agents:
SupportAgent:
tools:
search:
middleware: []
middlewareMergeMode: replaceThe effective chain is the environment-wide list U, followed by the merged per-tool list P, followed by the leaf tool: U ++ P ++ [leaf], outermost first. On agent tool bindings, middlewareMergeMode is prepend by default and can be append or replace; it changes only P. Environment tool bindings cannot set it. In the example, replacing P removes path-policy for SupportAgent, but both audit occurrences remain. To apply audit only to search, install it under that tool’s middleware instead of the environment-wide list. Compact entries such as path-policy@1.2.0 are also accepted. An installation’s account and version, when present, assert the selected declaration rather than selecting another release.
deployment.toolCompatibilityMode controls monomorphic middleware edge checks. structural-subtype (the default) accepts compatible projections and emits deployment warnings for input fields that a middleware discards. strict-equality requires equal runtime shapes while ignoring documentation and schema-version metadata. nominal requires the named command and its named input and error structures to match, then dynamically checks runtime values against those shapes. Universal middleware does not declare expected or presented schemas and leaves the next layer’s tool definition unchanged.
Like the other deployment options, toolCompatibilityMode is an environment property synchronized by golem environment sync-deployment-options or before deploying content changes. Updating it does not redeploy or recompile the active revision: the next deployment uses the new mode, while existing deployment snapshots retain their recorded mode and compiled plans for replay and rollback.
Secret policy
secretKeysReadable and secretKeysRevealable accept either "*" or a list of secret paths. Policies are narrowing-only across an agent’s binding layers, and revealable keys outside the effective readable scope are dropped with a deployment warning. The only supported secret merge mode is intersect, which is also the default.
environments:
production:
server: cloud
agents:
SupportAgent:
tools:
search:
secretKeysReadable: "*"
secretKeysRevealable:
- credentials.search.token
presets:
app-env:production:
tools:
search:
secretKeysReadable:
- credentials.search.token
- credentials.search.endpoint
secretKeysRevealable:
- credentials.search.tokenPublishing and consuming exact releases
A publisher opts a local tool into the registry for each environment. A successful deployment of this environment publishes a grantable release that records the component revision, tool version, metadata version, and metadata digest:
tools:
search: {}
toolReleases:
production:
search: {}
environments:
production:
server: cloudA release is not globally visible. A consumer selects an exact release once with tools.<name>.release and owns the provision configuration and bindings used by its deployment. Golem derives an automatically managed environment grant from this manifest declaration. The grant is an authorization checkpoint for adding tools to the environment, allows the deployment to read the selected release, and provides a revocation handle:
tools:
search:
release:
account: publisher@example.com
name: search
version: "1.2.0"
config:
index: consumer-documents
env:
LOG_LEVEL: info
environments:
production:
server: cloud
agents:
SupportAgent:
tools:
search:
secretKeysReadable:
- credentials.search.tokenRegistry subjects can use releaseId instead of the account, name, and version coordinate. A release ID remains pinned to that release. A coordinate-following grant moves to a replacement release published at the same coordinate when the publisher environment has versionCheck disabled; an ID-pinned grant stays on the previous release. Environments with versionCheck enabled accept only immutable releases and prevent mutable coordinate replacement while an active coordinate-following grant exists. Deployment planning shows the automatic grant changes implied by registry-backed tool declarations. Deployment creates missing grants before reading registry metadata or building bridge clients, and removes obsolete automatically managed grants. Protected system grants and grants created separately by an administrator are retained. The deploy actor must have permission to make the planned grant changes.
toolReleases is additive. Removing a name from the manifest does not de-publish its release, and rolling a deployment back does not undo publication. Manage lifecycle explicitly with golem tool release list, get, de-publish, and restore. De-publishing makes a release unavailable to new deployments but retains its grants; those grants become available again when the same release is restored. A deployment cannot restore or replace a de-published coordinate—you must restore it explicitly first. Superseded releases cannot be de-published or restored.
Tool publication changes are planned separately from staged deployment state. The CLI’s staged/current SAME or DIFFERENT comparison excludes tool publications; check the tool publication section of the deployment plan for those changes.
Publishing a new version does not move an existing consumer deployment. Selecting it creates a new deployment snapshot and reconciles its grant. Existing deployment snapshots and historical replay continue to use their pinned source. When loose publication replaces an existing coordinate, coordinate-following grants move to the replacement while ID-pinned grants continue to resolve the superseded release.
Runtime discovery and admission use the consumer deployment snapshot and the caller’s environment policy.
System-provided tools
Golem can ship two kinds of system-provided tool. A component-implemented built-in tool is a protected, immutable, grantable release. It behaves like any other registry release at consumption time: select its exact published coordinate with tools.<name>.release, then add a separate agents.<agent-type>.tools.<name> binding to make it available to that agent. Selecting a release does not itself bind the tool to an agent.
The default tools are the exception: the CLI selects and binds them automatically.
A native tool is compiled into the Golem host and provisioned as ambient. Do not declare it in the top-level tools map and do not specify a release coordinate. It is available to agents in the environment by default; an agent binding with the native tool’s name can narrow its parameters and policies.
Ambient tool names must not collide with application tools or selected account-owned tool releases. If a later Golem release adds an ambient tool with a name your application already uses, existing deployment snapshots remain unchanged, but preparing the next deployment fails until you resolve the name collision. Golem does not silently choose one implementation over another. This check applies to the entire ambient catalog, even when the manifest has no agent binding for that name.
Both kinds use the normal effective binding policy. In particular, configKeysReadable is narrowing-only: the effective scope is the intersection of the system or environment binding and the agent binding. Calls made by a native implementation through Golem’s config host helper are checked against that effective scope; running in the host does not grant unrestricted config access.
Golem currently ships these component-implemented built-ins:
read-file@0.3.0,write-file@0.3.0, andedit-file@0.3.0provide filesystem operations. Their agent bindings must grantfilesystemAccess: allowed.web-fetch@0.1.0performs read-only HTTP and HTTPS GET requests. It requires no filesystem grant and is marked open-world because it contacts external services.
For example, select and bind web-fetch as follows:
tools:
web-fetch:
release:
account: builtin-tool-owner@golem.cloud
name: web-fetch
version: 0.1.0
agents:
ResearchAgent:
tools:
web-fetch: {}The tool requires a URL on each call. It also accepts --timeout-ms (default 10000, allowed range 1–30000), --max-response-bytes (default 2097152, allowed range 1–5242880), --max-redirects (default 5, allowed range 0–10), and --convert-html-to-text (default false) as optional invocation arguments. These are not manifest parameters or deployment configuration, and the safety limits’ hard ceilings cannot be overridden. A zero redirect limit disables redirect following.
web-fetch returns the final URL, HTTP status, original content type when present, textual content, and whether the result was truncated. Non-success HTTP statuses are returned normally with supported textual bodies. HTML is returned as decoded source unless --convert-html-to-text is enabled. Binary responses, invalid text encodings, unsafe redirects, redirect cycles, and elapsed deadlines return typed errors.
Completed results and typed errors are durable and replay without another HTTP request. If execution is interrupted before the result is recorded, recovery may retry the GET request; endpoints should therefore tolerate repeated GETs.
Default tools
golem deploy automatically adds the built-in bash tool to every deployment. It selects the release bash@0.2.1 of builtin-tool-owner@golem.cloud, grants it to the environment, and binds it to every agent type with filesystemAccess: allowed and no configKeysReadable, secretKeysReadable or secretKeysRevealable scope, so the binding does not limit the agent’s config keys and secrets. The bash tool reads neither today: it works with the agent’s files and environment variables. golem ssh connects to this tool.
With the default tools on, everyone who may invoke an agent of the environment can run shell commands on it. Those commands can read and change the agent’s files, and they can read all environment variables of the agent, also a secret that is kept in one. A key scope of a binding does not hide an environment variable. To turn the default tools off for an environment, set defaults under its tools to an empty list:
environments:
production:
server: cloud
tools:
defaults: []tools.defaults selects the default tools of an environment. It has three forms:
- No text, or
"*": all default tools. A default tool that a later CLI version adds is included. []: no default tool.- A list of names, for example
[bash]: only those tools. A default tool that a later CLI version adds is not included.
bash is the only default tool now. A name that is not a default tool is a manifest error.
The same tools block holds the binding of a default tool. A binding named bash under environments.<environment-name>.tools merges with the default binding and applies to every agent type of that environment. For filesystemAccess, denied wins:
environments:
production:
server: cloud
tools:
defaults: [bash]
bash:
filesystemAccess: denieddefaults and middleware are the two reserved names of this block: each other name is the name of a tool.
Such a binding can also set the key scopes configKeysReadable, secretKeysReadable and secretKeysRevealable. A key scope limits what a tool reads from the agent’s config and secrets. The bash tool reads neither today, so a key scope changes nothing for it now. Each scope has three forms:
- No text, or
"*": no limit on that scope. This is the default. []: no key of that scope.- A list of paths: only those keys.
To allow no config key and no secret for bash in one environment:
environments:
production:
server: cloud
tools:
bash:
configKeysReadable: []
secretKeysReadable: []
secretKeysRevealable: []To allow one secret only, while the config keys stay without a limit:
environments:
production:
server: cloud
tools:
bash:
secretKeysReadable:
- credentials.github.tokenA binding named bash under agents.<agent-type>.tools is optional. An agent type without one uses the environment binding. An agent type with one gets only what both bindings allow, so it can narrow the environment binding and cannot widen it:
environments:
production:
server: cloud
tools:
bash:
secretKeysReadable:
- credentials.github.token
- credentials.gitlab.token
agents:
ReviewAgent:
tools:
bash:
secretKeysReadable:
- credentials.github.tokenIf the binding of an agent type lists a key that the environment binding does not allow, golem deploy prints a warning that names the key, and the tool does not get it. Add the key to the environment binding first. An environment binding with no text for a scope allows every key of that scope. The CLI gives the same warning when an agent type sets filesystemAccess: allowed and the environment binding denies the files.
A tools.bash declaration in the manifest replaces the default as a whole. The CLI then adds no release and no binding for bash: the manifest selects the release and binds it to each agent type, as for every other registry release.
An MCP import cannot supply a tool with the name of a default tool when the deployment has a tool with that name: the default tool, a tool named bash that the manifest declares, or a native bash of the server, which is in each deployment. golem deploy reads the tools of the imports before it changes anything, and it stops with a message when one of them is named bash. The server makes the same comparison when it makes the deployment, with the tools that the import lists at that moment, and it refuses the deployment. Give the import a prefix, exclude the tool from the import, or leave bash out of tools.defaults. With a native bash of the server, only the first two help.
This comparison uses the tools that an import lists at deploy time. If the tools of the imports cannot be read then, for example before the OAuth consent for an import is given, nothing shows that an import does not supply a tool named bash. The deployment is then refused when an import can supply that name. An import cannot supply it when it has a prefix, because each of its tools then has a name that starts with the prefix, or when its exclude or include filter leaves the name out; such an import gives only a warning, and the deployment goes on. So give an import that cannot be read yet a prefix, or exclude bash from it.
One case stays possible: the MCP server adds a tool named bash after the deployment. The tool of the deployment then keeps the name, and the imported tool is not available under it.
An ambient native tool of the server with the name of a default tool takes the place of the default tool, because it can be another version of the tool. The CLI then makes no grant for the default tool, and it prints one line that says so. The server keeps its own environment binding for a native tool, so the CLI applies a binding named bash under environments.<environment-name>.tools to every agent type, and prints one line that says so. A limit that the manifest sets for the environment, such as filesystemAccess: denied, stays in force. A binding named bash under an agent type narrows the tool further, as it does for the default tool.
The grant for a default tool is a part of the environment tool grant plan, as for every other registry release. A normal golem deploy shows the plan, asks for confirmation (--yes gives it) and makes the grant before it builds the deployment. golem deploy --plan and golem deploy --stage make no grant: on an environment that has no grant for the tool yet, --plan shows the grant plan and stops there, and --stage is refused. One normal deployment makes the grant. If the server does not have the release, the deployment stops and removes no grant; to deploy without the tool, leave it out of tools.defaults.
An agent that exists already gets a default tool on its next call after the deployment, as long as the deployment contains the agent’s component revision. An agent on an older component revision gets it when the agent is updated, for example with golem deploy --update-agents auto.
A build does not select deployment default tools. bridge.<language>.internal.tools: "*" includes application tools and the selected environment’s visible ambient native and MCP imported tools, not registry releases added only by deployment defaults. To generate a client for the default registry release of bash, declare tools.bash and select it for generation. An explicit declaration replaces the default, so also supply the consumer’s binding. See Generate typed clients for existing tools for a complete example.
Bridge generation
Prefer component tool dependencies for clients used by a consumer. golem build automatically generates each client’s guest SDK in the consumer’s language, as it does for agent dependencies. Keep the component’s language template. For a custom template, set componentTemplates.<template-name>.guestLanguage and apply that template to the consumer. No additional bridge.<language>.internal.tools selection is needed.
Declared local and registry-backed tools resolve from the application; otherwise the name is resolved from the selected environment’s ambient catalog and then from its MCP imports. Ambient and MCP imported names need no top-level tools declaration, release grant, or local implementation component. The CLI must be authenticated to read the selected environment’s metadata:
components:
my-app:consumer:
# Keep the component's existing dir, templates and build settings.
dependencies:
tools: [native-search, catalog-search]
tools:
native-search: {}
catalog-search: {}Dependencies select client generation; component or agent tool bindings expose the tool for invocation. A dependency does not create a binding, and a binding alone does not generate a client. The calling agent still needs the required runtime permissions. For a local tool, the provider builds before the consumer. A component cannot depend on its own guest bridge SDK; use the language SDK’s definition-owned client for a tool in the same component.
Use an explicit bridge selection when you need a separate generation target, such as another language or output directory:
bridge:
rust:
internal:
tools: [native-search]"*" under bridge.<language>.internal.tools includes all visible ambient and MCP-imported tools in addition to application tools. Explicit names avoid MCP discovery when ambient metadata already satisfies every request. Ambient and application tool names may not collide; ambient names take precedence over MCP projections, and earlier MCP imports take precedence over later imports.
Generated clients always invoke the canonical Golem tool name through tool-rpc. They contain no native host implementation ID, MCP endpoint, transport, or credentials. Native provision, binding, and middleware configuration is deployment-only and does not change the generated API or generation cache identity.
Run golem build to generate selected tool clients. golem generate-bridge does not expose a tool selector. Generation does not add a deployment binding or grant the calling agent runtime permissions. The generation guide shows generated output paths, consumer imports, typed calls, and regeneration for built-in tools and MCP imports in the supported languages.
For registry-backed tools, the generator reads only the release’s safe tool definition and metadata digest. It does not require the publisher’s WASM or permission to inspect the publisher component. Release identity and metadata digest are included in generation cache markers, so changing the selected release invalidates generated output. A missing grant is planned and created before metadata access; planning fails clearly when the deploy actor lacks permission to reconcile the grant.
Field reference
manifestVersion
Required manifest format marker: use manifestVersion: "1.6.0" in every manifest document. All loaded documents must use the same marker. The CLI validates it separately from the editor’s 1.6.0 JSON schema URL; it is not the application’s deployment version.
includes
Optional list of glob patterns that are used for adding search patterns for other Application Manifests when using auto discovery of them. The patterns are relative to the manifest document in which they are defined.
The default search pattern is **/golem.yaml, which searches for golem.yaml documents in every subdirectory
recursively. Templates and examples provided by Golem usually use more specific search patterns to make the lookups
more efficient.
The includes fields can be defined in one manifest only, usually in the project root directory.
Defining it multiple times results in validation error.
includes:
- components-dir/*/golem.yaml
- custom-templates/golem-*.yamlapp
Required application name which will be used as the deployment name for the application.
version
Optional application deployment version source: a nonempty static string, { env: VARIABLE_NAME }, or a git object. An environment variable must exist and be nonempty. If neither this field nor an environment override is set, deployment uses an empty version string. This is independent of manifestVersion and deployment.versionCheck.
Git versions are computed at the application root. Choose git: { hashOnly: true } for a short commit hash, or git: { tagPattern: "v*" } for a matching tag. Tag mode also accepts commitInfo (default true, includes distance/hash information) and hashFallback (default false, uses a hash if no tag matches). Both modes accept allowDirty (default false; when enabled, dirty versions end in -dirty) and staticFallback (used when Git is unavailable, the directory is not a repository, it has no commits, or no tag matches without a hash fallback). A dirty working tree still fails when allowDirty is false.
version:
git:
tagPattern: "v*"
hashFallback: true
environments:
production:
version: { env: RELEASE_VERSION }localServer
Optional local server configuration that defines where the built-in local preset lives. golem server run uses it to bind the local server, other golem commands targeting the preset use it to connect, golem server clean uses it to locate stored state, and local deployment subdomain expansion uses the relevant ports. CLI flags passed to golem server run override these values. Path values are resolved relative to the manifest that declares localServer. Do not set manifest ports to 0; port 0 is only allowed when passed directly as a golem server run port flag.
localServer.routerAddr
Optional bind address for the built-in local preset’s main API. golem server run binds to this address, and other golem commands targeting the preset connect to it. When it is 0.0.0.0, commands connect through 127.0.0.1. Must be an IPv4 address literal; host names are not supported. Defaults to 127.0.0.1 for binding and localhost for connections. The server refuses to bind an address that is not loopback while the configuration uses a well-known default secret, such as the local admin token; see golem-local-dev-server for the configuration file that replaces them. This field applies only to the main API. All listeners, including HTTP API and MCP, default to loopback. To expose HTTP API or MCP remotely, set worker_service.bind_address in the server configuration and replace all well-known secrets. Deployment subdomain values always expand to <subdomain>.localhost:<port>, which resolves only on the machine running the server. To reach local deployments from another machine, use domain with a host name that resolves there.
localServer.routerPort
Optional port for the built-in local preset’s main API. golem server run binds to this port, and other golem commands targeting the preset connect to it. Defaults to 9881. Do not set this to 0 in the manifest; use --router-port 0 directly with golem server run when you need an OS-assigned free port.
localServer.customRequestPort
Optional HTTP API port for local custom requests. Defaults to 9006; HTTP deployments using subdomain resolve to <subdomain>.localhost:<customRequestPort>. Requests are routed by matching their Host header against this expansion, so the server has to bind the same port: if golem server run is started with a different --custom-request-port (including 0), it warns that subdomain deployments are not reachable. Do not set this to 0 in the manifest; use --custom-request-port 0 directly with golem server run when you need an OS-assigned free port.
localServer.mcpPort
Optional MCP server port for local MCP requests. Defaults to 9007; MCP deployments using subdomain resolve to <subdomain>.localhost:<mcpPort>. Requests are routed by matching their Host header against this expansion, so the server has to bind the same port: if golem server run is started with a different --mcp-port (including 0), it warns that subdomain deployments are not reachable. Do not set this to 0 in the manifest; use --mcp-port 0 directly with golem server run when you need an OS-assigned free port.
localServer.portsFile
Optional path where the local server writes the actually-bound ports as JSON on startup. Useful together with direct golem server run port flags such as --custom-request-port 0.
localServer.dataDir
Optional directory used by golem server run and removed by golem server clean or golem server run --clean. Before deleting it, the CLI displays the resolved absolute path and asks for confirmation; pass -Y or --yes only after verifying the target. Filesystem roots are always rejected. Defaults to $XDG_STATE_HOME/golem. Pass -X to server clean to ignore the manifest and clean the platform default.
localServer.systemMemoryOverride
Optional positive byte-size string that overrides detected system memory for local agent admission and eviction, leaving room for other applications. For example, 2GiB sets a 2 GiB budget; the executor uses 80% for admission and reserves 20% for host overhead. The flag and the manifest accept the same case-insensitive units: 1mb and 1MB mean 1,000,000 bytes; 1MiB means 1,048,576 bytes. Whole-number quantities and ASCII spaces are accepted; use 1536 MiB instead of 1.5 GiB. Quote unitless byte values in YAML. Precedence is --system-memory-override, then the GOLEM__WORKER_EXECUTOR__MEMORY__SYSTEM_MEMORY_OVERRIDE environment variable (in bytes), then worker_executor.memory.system_memory_override in the golem server run --config file, then this field, then automatic host/cgroup memory detection. The value maps to the executor’s memory.system_memory_override. This is not a hard process RSS limit: compilation and other host allocations can exceed the budget.
localServer.agentFilesystemRoot
Optional root directory for deterministic agent filesystem directories, laid out as <root>/<environment_id>/<component_id>/<agent_segment>/. The agent segment is the agent name with each character that is not an ASCII letter, a digit, - or _ replaced by _, cut to 32 characters, then - and the BLAKE3 hash of the agent id. On macOS, the local server keeps agent files on Apfs storage at this root, and the default root is <data_dir>/agents, where <data_dir> is the resolved localServer.dataDir.
httpApi
Optional object for defining HTTP API deployments.
Deployments can be defined in multiple manifests, and they are merged during deployment. Entries that resolve to the same domain in one environment become one deployment with the agents of all entries. Their scheme, webhookUrl and openapiEndpoint must be the same, and an agent type that is in more than one of them must have the same options in each.
httpApi.deployments
Optional map of HTTP API deployments by environment name.
httpApi.deployments.<environment-name>
Optional list of HTTP API deployments for the environment.
httpApi.deployments.<environment-name>[*].domain
Full concrete domain for the deployment. Use domain for custom registered domains and custom server environments. Define exactly one of domain or subdomain.
httpApi.deployments.<environment-name>[*].subdomain
Built-in server subdomain for the deployment. Must be a single DNS label (lowercase letters, digits, and hyphens only). In a local environment it resolves to <subdomain>.localhost:9006 by default, or <subdomain>.localhost:<customRequestPort> when localServer.customRequestPort is set to a stable nonzero port. In a cloud environment it resolves to <subdomain>.apps.golem.cloud. Cannot be used with custom server environments — use domain instead. Define exactly one of domain or subdomain.
httpApi.deployments.<environment-name>[*].scheme
Public HTTP API scheme: http or https. When omitted, defaults to http for the built-in local server (including the implicit local target), and https for the built-in cloud server. Custom server environments require an explicit value. An explicit value always overrides the default; the management API URL does not determine the public scheme. This controls the origin advertised in generated OpenAPI documents, not TLS configuration.
httpApi.deployments.<environment-name>[*].openapiEndpoint
Optional OpenAPI path prefix, normalized with leading and trailing /. Defaults to /; the deployment serves the generated document at <prefix>openapi.json.
httpApi.deployments.<environment-name>[*].webhookUrl
Optional webhook URL for the deployment.
httpApi.deployments.<environment-name>[*].agents
Optional map of HTTP API deployment options by agent type name. An agent type can be listed in only one HTTP API deployment per environment, because the webhook URL of the agent type uses a single domain. One deployment can serve many agent types. To serve the same functionality on another domain, define a separate agent type for that domain that calls the original agent.
httpApi.deployments.<environment-name>[*].agents.<agent-type-name>.securityScheme
Optional security scheme for the agent in this deployment. Mutually exclusive with testSessionHeaderName.
httpApi.deployments.<environment-name>[*].agents.<agent-type-name>.testSessionHeaderName
Optional test session header name for the agent in this deployment. Mutually exclusive with securityScheme.
mcp
Optional object for defining MCP deployments and upstream imports.
mcp.deployments
Optional map of MCP deployments by environment name.
mcp.deployments.<environment-name>
Optional list of MCP deployments for the environment. Entries that resolve to the same domain become one deployment with the agents and tools of all entries; an agent type or tool that is in more than one of them must have the same options in each.
mcp.deployments.<environment-name>[*].domain
Full concrete domain for the MCP deployment. Use domain for custom registered domains and custom server environments. Define exactly one of domain or subdomain.
mcp.deployments.<environment-name>[*].subdomain
Built-in server subdomain for the MCP deployment. Must be a single DNS label (lowercase letters, digits, and hyphens only). In a local environment it resolves to <subdomain>.localhost:9007 by default, or <subdomain>.localhost:<mcpPort> when localServer.mcpPort is set to a stable nonzero port. In a cloud environment it resolves to <subdomain>.mcps.golem.cloud. Cannot be used with custom server environments — use domain instead. Define exactly one of domain or subdomain.
mcp.deployments.<environment-name>[*].agents
Optional map of MCP deployment options by agent type name.
mcp.deployments.<environment-name>[*].agents.<agent-type-name>.securityScheme
Optional security scheme for the agent in this MCP deployment.
mcp.imports
Optional map of upstream MCP imports by environment name. Each environment value is a list of import records.
mcp:
imports:
production:
- name: catalog
url: https://mcp.example.com/mcp
prefix: catalog
include: [search]mcp.imports.<environment-name>[*].url
Required upstream MCP server URL using HTTP or HTTPS, with a host and no userinfo or fragment.
mcp.imports.<environment-name>[*].name
Optional CLI-only import name matching [a-z][a-z0-9_-]*. It identifies the import to CLI commands and is not part of the deployed import contract.
mcp.imports.<environment-name>[*].auth
Optional inline authentication: either { bearer: TOKEN } or { basic: { user: USER, password: PASSWORD } }. Specify exactly one credential kind. Mutually exclusive with securityScheme.
mcp.imports.<environment-name>[*].securityScheme
Optional security scheme name for upstream authentication. Mutually exclusive with auth.
mcp.imports.<environment-name>[*].prefix
Optional lower-kebab-case prefix for the imported tool names.
mcp.imports.<environment-name>[*].include
Optional list of upstream tool names to import. Mutually exclusive with exclude.
mcp.imports.<environment-name>[*].exclude
Optional list of upstream tool names to omit. Mutually exclusive with include.
mcp.imports.<environment-name>[*].version
Optional MCP protocol version. The supported version is 2026-07-28; omitting it uses that default.
mcp.deployments.<environment-name>[*].tools
Optional map of tools-only MCP exports indexed by logical tool name. These calls have a component owner rather than an agent owner.
mcp.deployments.<environment-name>[*].tools.<tool-name>.ownerComponent
Required owner component name for calls to this tool. The component must bind the tool; an agent binding alone does not authorize these calls.
mcp.deployments.<environment-name>[*].tools.<tool-name>.securityScheme
Optional security scheme for the tools-only export.
mcp.deployments.<environment-name>[*].tools.<tool-name>.include
Optional command selection for the exported tool. Mutually exclusive with exclude.
mcp.deployments.<environment-name>[*].tools.<tool-name>.exclude
Optional command exclusion list for the exported tool. Mutually exclusive with include.
environments
Optional application environments by environment name.
environments.<environment-name>.version
Optional deployment version override for version. A static string or env source replaces the application source. Git options merge with the application source only within the same Git mode; changing modes or sources requires a complete source. A partial tag override can omit tagPattern only when inheriting application tag mode.
environments.<environment-name>.default
Optional boolean which when set to true marks the environment as default. Only one environment can be marked as default. If missing, the first environment is used as default.
environments.<environment-name>.account
Optional account that owns the application environment. When not specified then the current user will be used.
environments.<environment-name>.server
Optional server configuration for the environment. Accepted values:
localavailable since1.1.0cloudavailable since1.1.0
or a custom server object with the fields documented below.
environments.<environment-name>.server.url
Required URL for custom servers.
environments.<environment-name>.server.workerUrl
Optional custom URL for golem worker service.
environments.<environment-name>.server.allowInsecure
Optional boolean which defaults to false, when set to true it allows insecure connections to the server.
environments.<environment-name>.server.auth.oauth2
Optional boolean which when set to true selects OAuth2 based authentication.
environments.<environment-name>.server.auth.staticToken
Optional string static token for authentication when using static token based authentication.
environments.<environment-name>.componentPresets
Optional preset name or list of preset names which will be used for the application in the given environment.
environments.<environment-name>.cli.format
Optional default format for the environment, accepted values:
text(default value)available since1.1.0jsonavailable since1.1.0pretty-jsonavailable since1.1.0prettyavailable since1.1.0alias forpretty-jsonyamlavailable since1.1.0pretty-yamlavailable since1.1.0
environments.<environment-name>.cli.autoConfirm
Optional boolean which when set enables the auto-confirm (yes) flag by default.
environments.<environment-name>.cli.redeployAgents
Optional boolean which when set enables redeploy-agents flag by default.
environments.<environment-name>.cli.reset
Optional boolean which when set enables reset flag by default.
environments.<environment-name>.deployment.compatibilityCheck
Optional boolean to enable compatibility checks during deployment.
environments.<environment-name>.deployment.toolCompatibilityMode
Optional tool middleware compatibility mode. Accepted values are structural-subtype (the default), strict-equality, and nominal. Structural subtype mode warns about inputs discarded by a middleware; strict equality ignores documentation and schema-version metadata; nominal mode checks named command, input, and error structures and dynamically validates runtime shapes.
environments.<environment-name>.deployment.versionCheck
Optional boolean to enable strict version checks during deployment. Published tool releases are immutable when enabled. When disabled, publishing changed content at an existing coordinate creates a replacement release, marks the previous release as superseded, and moves active coordinate-following grants to the replacement. Strict environments cannot use mutable releases.
environments.<environment-name>.deployment.securityOverrides
Optional boolean to allow security overrides during deployment.
environments.<environment-name>.tools.defaults
Optional "*" or list of default tool names, "*" by default. Selects the default tools that the CLI adds to every deployment of the environment and binds to every agent type: "*" for all of them, [] for none, or a list of names for only those tools. An entry with the name of a default tool in the same tools block is the binding of that tool for the environment.
toolReleases.<environment-name>
Optional additive map of local tool names to publish as grantable releases when this environment is deployed. Each value is an empty object. Publication records the exact source and metadata of the deployed local tool and follows the environment’s deployment.versionCheck policy. Removing a name does not de-publish an existing release; use golem tool release de-publish <release-id> for that explicit lifecycle action.
toolMiddlewareReleases.<environment-name>
Optional additive map of local tool middleware names to publish as grantable releases when this environment is deployed. Each value is an empty object. Publication and lifecycle follow tool releases and the environment’s deployment.versionCheck policy.
components
Optional map of Golem components indexed by component-name-s used for defining components.
The components field can be defined in multiple manifest documents, but the used component-name-s must be
unique across all the used manifest documents. Using the same component-name more then once results in
validation error.
components:
pack-ns:component-name:
componentWasm: # ...
# ...
pack:comp-b:
componentWasm: # ...
# ...components.<component-name>.templates
Optional template name or list of template names which will be used for creating the component fields.
The template name must be one of that are defined in componentTemplates.
Templates can also inherit other templates, but every template may be inherited only through a single path: e.g. using two templates that both inherit the same template is rejected.
See componentTemplates and Template variable and functions
for defining templates.
components.<component-name>.presets
Optional map of presets used to define preset variations for a component.
A preset overrides component layer properties such as build steps, paths, configuration, tools and router mappings. It cannot contain dir, templates, or nested presets. Presets can also specify a components.<component-name>.presets.<preset-name>.default flag to mark it as the default preset for selection.
A component with custom presets always applies at least one custom preset. If no preset selected by the environment or the CLI matches this component, it applies the custom preset marked default: true. If none is marked, it applies the first custom preset in declaration order. The same rule applies independently to each component template and agent with custom presets.
Presets named app-env:<environment-name> are environment presets, not custom presets. They apply only for the matching environment and do not participate in default selection.
To keep a preset opt-in, add an empty preset marked default: true:
components:
my-app:service:
presets:
standard:
default: true
debug:
env:
RUST_LOG: debugThe standard preset adds no overrides. The debug preset applies only when selected by componentPresets: debug in the environment or by -P debug on the CLI. Use the same empty-default pattern under a template’s or agent’s presets to keep its other presets opt-in.
components.<component-name>.presets.<preset-name>.default
Preset specific components.<component-name>.default.
Optional boolean which when set to true marks the custom preset as the default for selection. The default applies when no selected preset name matches this component. If no custom preset is marked default: true, the first custom preset in declaration order is the default, even if it is the only custom preset. Environment presets (app-env:<environment-name>) do not participate in default selection.
components.<component-name>.dir
Optional base directory for resolving component paths. The path is relative to the manifest document.
components.<component-name>.buildMergeMode
Optional merge mode for components.<component-name>.build. Accepted values:
append(default value)available since1.1.0prependavailable since1.1.0replaceavailable since1.1.0
components.<component-name>.files
Optional list of files entries, which can be used for defining the Initial File System for the component.
components:
pack-ns:component-name:
# ...
files:
- sourcePath: ./files/foo.txt
targetPath: /files/foo.txt
permissions: read-only
- sourcePath: ./files/bar.txt
targetPath: /files/bar.txt
permissions: read-writecomponents.<component-name>.filesMergeMode
Optional merge mode for components.<component-name>.files. Accepted values:
append(default value)available since1.1.0prependavailable since1.1.0replaceavailable since1.1.0
components.<component-name>.files[*].sourcePath
Required source path of the file to be added to the Initial File System. The path can be a file path relative to the manifest document or an URL.
components.<component-name>.files[*].targetPath
Required target path of the file in the Initial File System. The path must be an absolute path.
components.<component-name>.files[*].permissions
Optional string enum which controls file permissions. Accepted values:
read-only(default value)available since1.1.0read-writeavailable since1.1.0
components.<component-name>.plugins
Optional list of component plugin installation entries,
components.<component-name>.pluginsMergeMode
Optional merge mode for components.<component-name>.plugins. Accepted values:
append(default value)available since1.1.0prependavailable since1.1.0replaceavailable since1.1.0
components.<component-name>.plugins[*].name
Required name of the plugin.
components.<component-name>.plugins[*].version
Required version of the plugin.
components.<component-name>.plugins[*].account
Optional account used for installing the plugin.
components.<component-name>.plugins[*].parameters
Optional string map of plugin parameters.
components.<component-name>.configSchema
Optional component configuration schema with schema and declarations fields. Templates and presets can also set it; a later layer replaces the schema rather than merging declarations.
components.<component-name>.config
Optional configuration for the component.
components.<component-name>.initialCard
Optional initial permission card. The lowerBound and upperBound objects each accept positive and negative lists of permission strings. Omitted bounds and lists are empty. See Initial tool permissions for an example and validation rules.
components.<component-name>.env
Optional string map of environment variables for the component. Names must be uppercase. Names starting with GOLEM_ are reserved and can be overridden by Golem.
components.<component-name>.tools
Optional map of tool bindings inherited by agents exported by the component and used as the authorization baseline for fresh component owners, including tools-only MCP calls. Bindings do not generate clients; use components.<component-name>.dependencies.tools for automatic client generation.
components.<component-name>.toolsMergeMode
Optional merge mode for components.<component-name>.tools. Accepted values:
upsert(default value)available since1.1.0replaceavailable since1.1.0removeavailable since1.1.0
components.<component-name>.dependencies.agents
Optional list of agent dependencies. Each entry is component-name/AgentTypeName or { component: component-name, name: AgentTypeName }. The provider builds before the consumer, and golem build generates guest clients in the consumer’s language. Agent names are case-sensitive. A component cannot depend on itself.
components:
acme:frontend:
templates: ts
dependencies:
agents:
- acme:backend/CounterAgentcomponents.<component-name>.dependencies.tools
Optional canonical tool names or component/name references whose guest clients the component consumes. golem build automatically generates these clients in the consumer’s language. No explicit bridge selection is required. A declared local tool creates a component build dependency; a declared registry-backed tool uses its selected release. A name with no declaration is resolved from the selected environment’s ambient native tools first and MCP imports second, without requiring a local implementation component or release grant. Dependencies do not add runtime bindings; configure components.<component-name>.tools or the calling agent’s tools separately. A local dependency cannot refer to the consumer itself.
components.<component-name>.envMergeMode
Optional merge mode for components.<component-name>.env. Accepted values:
upsert(default value)available since1.1.0replaceavailable since1.1.0removeavailable since1.1.0
components.<component-name>.nodeHttpRouters
Optional build-time router table for TypeScript components only. Each layer that specifies this field replaces the entire table; entries are not merged. Keys are canonical decimal strings from "1" to "65535" (no leading zeroes). These are logical Node HTTP listen ports, not sockets opened on the host. Router names must be unique within the component.
Each entry requires name (the router name) and mount (the HTTP mount path). Optional auth is a boolean, and optional cors is a list of allowed origin strings.
components:
acme:api:
templates: ts
nodeHttpRouters:
"3000":
name: api
mount: /api
auth: false
cors: ["https://example.com"]components.<component-name>.componentWasm
File path for the built WASM component. It must be nonempty after templates and presets resolve.
The path is relative to the effective component directory, including when inherited from a template in another manifest.
components:
pack-ns:component-name:
# ...
componentWasm: build/component.wasmcomponents.<component-name>.outputWasm
Optional file path for the output WASM component which is ready to be uploaded to Golem.
The path is relative to the effective component directory. Defaults to <golemTempDir>/final-wasm/<component-name>.wasm.
components:
pack-ns:component-name:
# ...
outputWasm: build/output.wasmcomponents.<component-name>.build
Optional list of build steps that creates components.<component-name>.componentWasm.
Each build step can be one of:
- an external command (with
commandfield) - a QuickJS crate generation step (with
generateQuickjsCratefield) - a QuickJS d.ts generation step (with
generateQuickjsDtsfield) - an inject to prebuilt QuickJS step (with
injectToPrebuiltQuickjsfield) - a JS preinitialization step (with
preinitializeJsfield)
components:
pack-ns:component-name:
build:
- command: bindgen-tool src component.wasm
- command: build-tool src component.wasmcomponents.<component-name>.build[*].generateQuickjsCrate
QuickJS crate output directory. This build variant requires wit (the WIT directory) and jsModules (a map of module names to JavaScript paths); world optionally selects a WIT world. All paths resolve against the effective component directory.
build:
- generateQuickjsCrate: generated/quickjs
wit: wit
jsModules:
main: src/main.js
- generateQuickjsDts: generated/types.d.ts
wit: witcomponents.<component-name>.build[*].generateQuickjsDts
TypeScript declaration output path. Requires wit (the WIT directory); world optionally selects a WIT world. Paths resolve against the effective component directory.
components.<component-name>.build[*].injectToPrebuiltQuickjs
Prebuilt QuickJS WASM input path. Requires module (the JavaScript module path) and into (the output WASM path). All paths resolve against the effective component directory.
components.<component-name>.build[*].preinitializeJs
WASM input path for JavaScript preinitialization. Requires into (the output WASM path). Both paths resolve against the effective component directory.
components.<component-name>.build[*].command
Required external command that will be used as a build step for creating
components.<component-name>.componentWasm.
components.<component-name>.build[*].dir
Optional directory path which will be used as working directory when executing
components.<component-name>.build[*].command.
The path is relative to the effective component directory, and defaults to . (that directory).
components.<component-name>.build[*].env
Optional string map of environment variables for the build command.
components.<component-name>.build[*].rmdirs
Optional list of directory paths which will be deleted before executing the command.
The path is relative to components.<component-name>.build[*].dir.
The rmdirs field is useful when a binding generator does not automatically clean stale bindings.
Directories are not removed if the command is skipped because of up-to-date checks, see
components.<component-name>.build[*].sources and
components.<component-name>.build[*].targets.
Directories are removed before executing components.<component-name>.build[*].mkdirs.
components.<component-name>.build[*].mkdirs
Optional list of directory paths which will be created before executing the command if they do not exists.
The path is relative to components.<component-name>.build[*].dir.
The mkdirs field is useful when a build of binding generator tool does not automatically create
required nested folders.
Directories are not created if the command is skipped because of up-to-date checks, see
components.<component-name>.build[*].sources and
components.<component-name>.build[*].targets.
Directories are created after executing components.<component-name>.build[*].rmdirs.
components.<component-name>.build[*].sources
Optional list of paths and globs which are used as sources for performing up-to-date checks.
If defined then components.<component-name>.build[*].targets also have to be used.
The up-to-date check
- skips executing
components.<component-name>.build[*].command - if all matching files defined by
components.<component-name>.build[*].targets - are newer then the matched files defined by
sources.
components:
pack-ns:component-name:
# ...
build:
- command: build-tool src-dir out.wasm
sources:
- src-dir/*
targets:
- out.wasmcomponents.<component-name>.build[*].targets
Optional list of paths and globs which are used as targets for performing up-to-date checks.
If defined then components.<component-name>.build[*].sources also have to be used.
See components.<component-name>.build[*].sources for up-to-date check details.
components.<component-name>.customCommands
Optional map of component specific external commands, which are useful for defining e.g. one time installation or update related commands for the component.
The commands can be executed using:
golem exec command-nameMultiple components can use the same command-name, the above command will execute all matching
commands in this case, both component specific and project ones.
For defining project level custom commands see customCommands.
components:
pack-ns:component-name:
# ...
customCommands:
npm-install:
- command: npm installcomponents.<component-name>.customCommands.<command-name>[*].dir
Optional working directory relative to the effective component directory, including for commands inherited from templates. Defaults to . (the component directory), unlike project-level custom commands, which use the declaring manifest directory.
components.<component-name>.customCommands.<command-name>[*].env
components.<component-name>.customCommands.<command-name>[*].rmdirs
components.<component-name>.customCommands.<command-name>[*].mkdirs
components.<component-name>.customCommands.<command-name>[*].sources
components.<component-name>.customCommands.<command-name>[*].targets
components.<component-name>.clean
Optional list of paths added to golem clean, relative to the effective component directory, including when inherited from a template. Project-level clean paths remain relative to their declaring manifest.
clean
Optional list of paths which are added as targets to the golem clean command.
The paths are relative to the manifest document.
The clean command deletes the following paths:
- build and custom command
targets - the paths defined in common and component specific
cleanfields.
Related fields:
customCommands
Optional map of custom external commands, which are useful for defining e.g. one time installation or update related project commands.
The commands can be executed using:
golem exec command-nameComponents specific custom commands can use the same command-name, the above command will execute all matching
commands in this case, both component specific and project ones.
For defining component specific custom commands see components.<component-name>.customCommands.
customCommands:
npm-install:
- command: npm installcustomCommands.<command-name>[*].dir
Optional directory path which will be used as working directory when executing
customCommands.<command-name>[*].command.
The path is relative to the manifest document, and defaults to ..
customCommands.<command-name>[*].command
Required external command to execute for this custom command step.
customCommands.<command-name>[*].env
Optional string map of environment variables for the command.
customCommands.<command-name>[*].rmdirs
Optional list of directory paths which will be deleted before executing the command.
The path is relative to customCommands.<command-name>[*].dir.
The rmdirs field is useful when a binding generator does not automatically clean stale bindings.
Directories are not removed if the command is skipped because of up-to-date checks, see
customCommands.<command-name>[*].sources and
customCommands.<command-name>[*].targets.
Directories are removed before executing customCommands.<command-name>[*].mkdirs.
customCommands.<command-name>[*].mkdirs
Optional list of directory paths which will be created before executing the command if they do not exists.
The path is relative to customCommands.<command-name>[*].dir.
The mkdirs field is useful when a build of binding generator tool does not automatically create
required nested folders.
Directories are not created if the command is skipped because of up-to-date checks, see
customCommands.<command-name>[*].sources and
customCommands.<command-name>[*].targets.
Directories are created after executing customCommands.<command-name>[*].rmdirs.
customCommands.<command-name>[*].sources
Optional list of paths and globs which are used as sources for performing up-to-date checks.
If defined then customCommands.<command-name>[*].targets also have to be used.
The up-to-date check
- skips executing
customCommands.<command-name>[*].command - if all matching files defined by
customCommands.<command-name>[*].targets - are newer then the matched files defined by
sources.
customCommands.<command-name>[*].targets
Optional list of paths and globs which are used as targets for performing up-to-date checks.
If defined then customCommands.<command-name>[*].sources also have to be used.
See customCommands.<command-name>[*].sources for up-to-date check details.
componentTemplates
Optional map of named templates, which can be used in components.<component-name>.templates.
Templates help in extracting common build patterns and reuse them for multiple components.
The templates field can be defined in multiple application manifest documents, but the template names must be
unique.
See Template variable and functions for more information about templating.
componentTemplates.<template-name>.guestLanguage
Optional guest language of the components built with the template: ts, effect, rust, scala, moonbit or go.
A component’s guest language comes from the templates applied to it, directly or through template inheritance. The CLI uses it for language specific features, such as dependency checks, bridge generation and the REPL. The built-in templates (e.g. ts, rust, scala) declare their language, so custom templates inheriting them don’t need to declare it; custom templates that don’t inherit a built-in template can declare it to enable these features. The templates applied to a component must not declare different languages.
componentTemplates.<template-name>.templates
Optional template name or list of template names to inherit. Every template may be inherited through only one path, as for components.<component-name>.templates.
componentTemplates.<template-name>.componentWasm
componentTemplates.<template-name>.outputWasm
componentTemplates.<template-name>.buildMergeMode
componentTemplates.<template-name>.build
componentTemplates.<template-name>.build[*].command
componentTemplates.<template-name>.build[*].dir
componentTemplates.<template-name>.build[*].env
componentTemplates.<template-name>.build[*].rmdirs
componentTemplates.<template-name>.build[*].mkdirs
componentTemplates.<template-name>.build[*].sources
componentTemplates.<template-name>.build[*].targets
componentTemplates.<template-name>.customCommands
componentTemplates.<template-name>.customCommands.<command-name>[*].dir
componentTemplates.<template-name>.customCommands.<command-name>[*].env
componentTemplates.<template-name>.customCommands.<command-name>[*].rmdirs
componentTemplates.<template-name>.customCommands.<command-name>[*].mkdirs
componentTemplates.<template-name>.customCommands.<command-name>[*].sources
componentTemplates.<template-name>.customCommands.<command-name>[*].targets
componentTemplates.<template-name>.clean
componentTemplates.<template-name>.config
componentTemplates.<template-name>.env
componentTemplates.<template-name>.envMergeMode
componentTemplates.<template-name>.nodeHttpRouters
componentTemplates.<template-name>.plugins
componentTemplates.<template-name>.pluginsMergeMode
componentTemplates.<template-name>.files
componentTemplates.<template-name>.filesMergeMode
componentTemplates.<template-name>.files[*].sourcePath
componentTemplates.<template-name>.files[*].targetPath
componentTemplates.<template-name>.files[*].permissions
componentTemplates.<template-name>.presets
componentTemplates.<template-name>.presets.<preset-name>.default
agents
Optional map of agents by agent type name.
agents.<agent-type-name>.templates
Optional template name or list of template names which will be used for creating the agent fields.
As for components, every template may be inherited only through a single path: e.g. listing a template together with another template that inherits it is rejected.
Related fields:
agents.<agent-type-name>.config
Optional configuration for the agent.
Related fields:
agents.<agent-type-name>.env
Optional string map of environment variables for the agent. Names must be uppercase; GOLEM_ names are reserved.
Related fields:
agents.<agent-type-name>.initialCard
Optional initial permission card with the same shape as components.<component-name>.initialCard. Agent templates and presets can also set this field.
Related fields:
agents.<agent-type-name>.tools
Optional map of tool bindings merged over bindings inherited from the implementing component. Agent bindings affect real agents only and cannot authorize fresh component owners.
Related fields:
agents.<agent-type-name>.toolsMergeMode
Optional merge mode for agents.<agent-type-name>.tools: upsert (the default), replace, or remove.
agents.<agent-type-name>.envMergeMode
Optional merge mode for agents.<agent-type-name>.env. Accepted values:
upsert(default value)available since1.1.0replaceavailable since1.1.0removeavailable since1.1.0
Related fields:
agents.<agent-type-name>.plugins
Optional list of plugin installations for the agent.
Related fields:
agents.<agent-type-name>.pluginsMergeMode
Optional merge mode for agents.<agent-type-name>.plugins. Accepted values:
append(default value)available since1.1.0prependavailable since1.1.0replaceavailable since1.1.0
agents.<agent-type-name>.plugins[*].name
Required name of the plugin.
agents.<agent-type-name>.plugins[*].version
Required version of the plugin.
agents.<agent-type-name>.plugins[*].account
Optional account used for installing the plugin.
agents.<agent-type-name>.plugins[*].parameters
Optional string map of plugin parameters.
agents.<agent-type-name>.files
Optional list of files entries for defining the Initial File System for the agent.
Related fields:
agents.<agent-type-name>.filesMergeMode
Optional merge mode for agents.<agent-type-name>.files. Accepted values:
append(default value)available since1.1.0prependavailable since1.1.0replaceavailable since1.1.0
agents.<agent-type-name>.files[*].sourcePath
Required source path of the file. The path can be a file path relative to the manifest document or an URL.
agents.<agent-type-name>.files[*].targetPath
Required target path of the file. The path must be an absolute path.
agents.<agent-type-name>.files[*].permissions
Optional string enum which controls file permissions. Accepted values:
read-only(default value)available since1.1.0read-writeavailable since1.1.0
agents.<agent-type-name>.presets
Optional map of presets for the agent.
An agent with custom presets always applies at least one custom preset. If no selected preset name matches this agent, it applies the custom preset marked default: true, or the first custom preset in declaration order if none is marked. Environment presets (app-env:<environment-name>) apply only for the matching environment and do not participate in default selection. To keep other custom presets opt-in, add an empty preset marked default: true, as shown for components.<component-name>.presets.
Related fields:
agents.<agent-type-name>.presets.<preset-name>.default
Preset specific agents.<agent-type-name>.default.
Optional boolean which when set to true marks the custom preset as the default for selection. The default applies when no selected preset name matches this agent. If no custom preset is marked default: true, the first custom preset in declaration order is the default, even if it is the only custom preset. Environment presets (app-env:<environment-name>) do not participate in default selection.
tools
Optional map of canonical tool declarations indexed by the tool’s lower-kebab-case logical name. A declaration either matches a locally discovered implementation, selects one with component, or selects an exact published release with release. Release coordinates are specified only here; agents, component dependencies, bridge generation, and other consumers refer to the logical name. Provision fields such as config, env, plugins, and files belong to the consuming deployment.
tools.<tool-name>.release
Optional exact published release reference. Specify either releaseId or all of account, name, and version. Golem derives and reconciles an automatically managed environment grant from this declaration; planned changes remain visible during deployment. Omit release for a locally implemented tool.
tools.<tool-name>.component
Optional local implementing component name. Use it to disambiguate components that export the same tool name and to let a name-only dependencies.tools entry resolve to its local build dependency.
tools.middleware.<middleware-name>
Optional canonical tool middleware declaration. Select a local implementation with component or an exact published release with release; these source forms are mutually exclusive. Consumer-owned provision fields include config, env, plugins, and files.
environments.<environment-name>.tools.middleware
Optional ordered environment-wide middleware list applied before every per-tool middleware chain. Only universal (schema-agnostic) middleware is accepted here. Duplicate middleware occurrences are preserved.
agents.<agent-type-name>.tools.<tool-name>.middleware
Optional ordered per-tool middleware list accepting universal or monomorphic middleware. Entries may be compact name@version strings or records with name, optional version, account, parameters, and filesystemAccess.
agents.<agent-type-name>.tools.<tool-name>.middlewareMergeMode
Optional agent per-tool middleware list merge mode: prepend (the default), append, or replace. It is not valid on environment tool bindings and never changes the environment-wide middleware list.
agents.<agent-type-name>.tools.<tool-name>.filesystemAccess
Optional filesystem policy for a tool binding. Accepted values are unset, allowed, and denied. Middleware installation records support the same field per occurrence.
bridge
Optional object for configuring Bridge SDK generation.
bridge.<language>
Optional language configuration for ts, effect, rust, scala, moonbit, or go. Each language has separate external and internal target objects. An empty object selects nothing; configure agents or internal.tools explicitly. Component dependencies also generate internal clients automatically.
bridge:
ts:
external:
agents: "*"
internal:
agents: "*"bridge.<language>.external
Optional target object for clients that invoke agents from outside Golem. Supports agents and outputDir, not tools.
bridge.<language>.internal
Optional target object for guest clients used inside Golem. Supports agents, tools, and outputDir.
bridge.<language>.external.agents
Optional agent selection: an agent type name, component matcher, list of these, or "*" for all application agents. Defaults to an empty selection.
bridge.<language>.internal.agents
Optional agent selection with the same syntax and empty default as bridge.<language>.external.agents.
bridge.<language>.external.outputDir
Optional output base directory, relative to the manifest that declares bridge. Each client gets its own subdirectory. Defaults to <golemTempDir>/bridge-sdk/<language> for external clients.
bridge.<language>.internal.outputDir
Optional output base directory, relative to the manifest that declares bridge. Each client gets its own subdirectory. Defaults to <golemTempDir>/bridge-sdk/<language>/internal for internal clients.
bridge.rust.<target>.additionalDerives
Optional list of Rust derive paths for generated agent types, independently for external and internal targets. Requires a nonempty agents selection.
bridge.rust.<target>.additionalDependencies
Optional dependency map for each Rust target (external or internal). Requires a nonempty agents selection. Each value is a version string or an object with optional version, path, git, package, features, defaultFeatures, branch, tag, rev, workspace, and optional fields. Use camelCase here, including defaultFeatures, rather than Cargo’s hyphenated keys.
bridge.<language>.internal.tools
Optional canonical tool names, local component matchers, or "*" for generated guest bridge clients. Names declared under tools resolve to their local or registry-backed implementations; undeclared names resolve from the selected environment’s ambient native tools and MCP imports. "*" includes every visible tool. Release coordinates and native host identities cannot be specified here.
secretDefaults
Optional map of secret defaults by environment name.
secretDefaults.<environment-name>
Optional object of secret default values for the environment, nested by secret path (e.g. db: { password: ... } for the db.password secret). Defaults are only applied to secrets that do not exist yet in the environment. String values can reference environment variables with {{ VAR }}; these are only required for secrets that get created.
retryPolicyDefaults
Optional map of retry policy defaults by environment name. Policies defined here are created in the environment during deployment if they don’t already exist.
retryPolicyDefaults.<environment-name>
Optional map of retry policy records indexed by policy name for the environment.
retryPolicyDefaults:
production:
transient:
priority: 10
predicate:
propEq: { property: status-code, value: 503 }
policy:
countBox:
maxRetries: 3
inner:
exponential: { baseDelay: { secs: 0, nanos: 100000000 }, factor: 2.0 }retryPolicyDefaults.<environment-name>.<policy-name>
Retry policy record with required priority, predicate, and policy fields. Its map key supplies the unique name; there is no name field.
retryPolicyDefaults.<environment-name>.<policy-name>.priority
Required integer defining selection priority — higher values are evaluated first.
retryPolicyDefaults.<environment-name>.<policy-name>.predicate
Required predicate tree defining when this policy applies. Supports composable predicates including
property comparisons (propEq, propNeq, propGt, propGte, propLt, propLte),
property checks (propExists, propIn, propMatches, propStartsWith, propContains),
and logical combinators (and, or, not). Use booleans for unconditional predicates, single-key objects for operators, and two-element lists for and and or. Comparison values are plain strings, integers, or booleans, not type-tagged API objects.
retryPolicyDefaults.<environment-name>.<policy-name>.policy
Required retry policy tree defining the retry strategy. Supports base strategies
("immediate", "never", periodic, exponential, fibonacci) and composable modifiers
(countBox, timeBox, clamp, addDelay, jitter, filteredOn, andThen, union, intersect). Operator names are camelCase single-key objects, not type discriminators. Duration fields accept strings such as 100ms or 1s; for example, periodic: 1s.
resourceDefaults
Optional map of quota resource defaults by environment name.
resourceDefaults.<environment-name>
Optional map of resource records indexed by resource name for the environment.
resourceDefaults:
production:
requests:
limit: { type: Rate, value: 10, period: second, max: 20 }
enforcementAction: throttle
unit: request
units: requestsresourceDefaults.<environment-name>.<resource-name>
Resource record with required limit, enforcementAction, unit, and units fields. Its map key supplies the resource name; there is no name field.
resourceDefaults.<environment-name>.<resource-name>.limit
Required resource limit definition. Can be one of:
- Rate limit:
{"type": "Rate", "value": <int>, "period": <timePeriod>, "max": <int>} - Capacity limit:
{"type": "Capacity", "value": <int>} - Concurrency limit:
{"type": "Concurrency", "value": <int>}
Where timePeriod is one of: second, minute, hour, day, month, year.
resourceDefaults.<environment-name>.<resource-name>.enforcementAction
Required enforcement action for the resource, accepted values:
rejectavailable since1.1.0throttleavailable since1.1.0terminateavailable since1.1.0
resourceDefaults.<environment-name>.<resource-name>.unit
Required string for the single unit of measurement (e.g., token, request).
resourceDefaults.<environment-name>.<resource-name>.units
Required string for the plural units of measurement (e.g., tokens, requests).
Fields and changes by releases
library tocomponents.<component-name>[*].componentTyperesetWorkers to resetAgentstempDir, witDeps, components.<component-name>.sourceWit, components.<component-name>.generatedWit, components.<component-name>.linkedWasm, components.<component-name>.componentType, components.<component-name>.dependencies, components.<component-name>.dependenciesMergeModehttpApi.definitions subtreelinkedWasm to outputWasmhttpApi to deployment-only model