golem-profiles-and-environments

name	golem-profiles-and-environments
description	Understanding Golem CLI profiles, application environments, and component presets. Use when configuring deployment targets, switching between local and cloud servers, managing CLI profiles, defining environment-specific presets, or understanding how environments, presets, and profiles interact.

Profiles, Environments, and Presets

Golem uses three related but distinct concepts for targeting deployments:

• CLI Profiles — stored in ~/.golem/config.json, define how the CLI connects to a Golem server (URL, authentication)
• App Environments — defined in golem.yaml under environments:, describe deployment targets with server, account, presets, and CLI/deployment options
• Component/Agent Presets — defined in golem.yaml under presets: within components, agents, or component templates, provide named configuration overrides (env vars, plugins, files, config) that environments can activate

How They Relate

CLI Profile (connection settings)
    ↑ resolved from
App Environment (deployment target)
    ↓ activates
Component/Agent Presets (config overrides)

When you run golem deploy, the CLI:

1. Selects an environment from the manifest (via --local, --cloud, -e <name>, or the default: true environment)
2. Resolves connection settings — either from the environment's server: field, or falls back to the active CLI profile
3. Activates presets listed in the environment's componentPresets: field, merging their overrides into the resolved configuration

CLI Profiles

Profiles are global CLI configuration stored in ~/.golem/config.json. They define server URLs and authentication credentials.

Built-in profiles

Profile	Server	Auth
local	http://localhost:9881	Built-in local token
cloud	https://release.api.golem.cloud	OAuth2

Managing profiles

golem profile new                          # Interactive setup
golem profile new my-staging --url https://staging.example.com                 # OAuth2 (default)
golem profile new my-staging --url https://staging.example.com --auth static   # static token (prompted, masked)
golem profile new my-staging --url https://staging.example.com --static-token "..."  # static token inline
golem profile list                         # List all profiles
golem profile switch my-staging            # Set active profile
golem profile get                          # Show active profile
golem profile get my-staging               # Show specific profile
golem profile delete my-staging            # Delete a profile
golem profile config my-staging set-format json  # Set default output format

Authentication mode is explicit via --auth: oauth2 (default — interactive browser login on first use) or static (a pre-issued token). Passing --static-token implies --auth static; --auth static without a token prompts for one (masked). A token cannot be combined with --auth oauth2.

Global flags

golem --profile my-staging deploy          # Use a specific profile for this command
golem -L deploy                            # Shortcut: use "local" environment/profile
golem -C deploy                            # Shortcut: use "cloud" environment/profile

Profile fields

Field	Description
custom_url	Golem Component service URL
custom_worker_url	Golem Worker service URL (defaults to custom_url)
allow_insecure	Accept invalid TLS certificates
auth	Authentication — staticToken or OAuth2
config.default_format	Default CLI output format (text or json)

App Environments

Environments are defined in golem.yaml and represent named deployment targets. They specify which server to deploy to, which presets to activate, and optional CLI/deployment behavior.

For deployment subdomain fields, the environment's server controls expansion. A built-in local server resolves HTTP API subdomains to *.localhost:9006 and MCP subdomains to *.localhost:9007 by default; a built-in cloud server resolves them to *.apps.golem.cloud and *.mcps.golem.cloud. The environment name itself does not control the expansion.

Basic example

environments:
  local:
    default: true                    # Selected when no -e flag is given
    server: local                    # Use built-in local server
    componentPresets: local          # Activate the "local" preset
  cloud:
    server: cloud                    # Use built-in Golem Cloud
    componentPresets: cloud

Custom server example

environments:
  staging:
    server:
      url: https://staging.example.com
      auth:
        staticToken: "{{ STAGING_TOKEN }}"
    componentPresets: staging
  prod:
    account: my-org                  # Cloud account to deploy to
    server: cloud
    componentPresets: prod

Environment fields

Field	Type	Description
default	true	Mark as default environment (only one allowed)
account	string	Cloud account name for deployment
server	local, cloud, or custom object	Server connection settings
componentPresets	string or string[]	Preset name(s) to activate
cli	object	CLI behavior overrides (see below)
deployment	object	Deployment option overrides (see below)
version	object or string	Per-environment version override — see golem-deployment-version

Server options

• local — built-in local server (http://localhost:9881 by default, configurable through manifest localServer.routerAddr and localServer.routerPort)
• cloud — Golem Cloud (https://release.api.golem.cloud) with OAuth2
• Custom object with url, optional workerUrl, optional allowInsecure, and auth (oauth2: true or staticToken: "...")

CLI options (cli:)

environments:
  local:
    server: local
    cli:
      format: json                   # Default output format
      autoConfirm: true              # Auto-answer "yes" to prompts
      redeployAgents: true           # Equivalent to --reset on deploy
      reset: true                    # Reset all state on deploy

Deployment options (deployment:)

environments:
  local:
    server: local
    deployment:
      compatibilityCheck: false      # Skip component compatibility checks
      versionCheck: false            # Enforce unique deploy versions; false = allow re-use (default)
      securityOverrides: true        # Allow security config overrides

Selecting an environment

Flag	Effect
-L / --local	Select the local environment (or local profile if no manifest)
-C / --cloud	Select the cloud environment (or cloud profile if no manifest)
-e <name>	Select a named environment from the manifest
(none)	Use the default: true environment, or fall back to active profile

Managing environments

golem environment list                     # List environments on the server
golem environment sync-deployment-options  # Sync deployment options to the server

Environment-scoped manifest sections

Load golem-edit-manifest for the full schema and editing rules of these manifest sections.

Several top-level manifest sections are keyed by environment name:

httpApi:
  deployments:
    local:                           # Only deployed to "local" environment
      - subdomain: my-app  # resolves to my-app.localhost:9006 by default
        agents:
          MyAgent: {}
    cloud:
      - subdomain: my-app  # resolves to my-app.apps.golem.cloud
        agents:
          MyAgent: {}

mcp:
  deployments:
    local:
      - subdomain: my-mcp  # resolves to my-mcp.localhost:9007 by default

secretDefaults:
  local:
    apiKey: "test-key"
  cloud:
    apiKey: "{{ PROD_API_KEY }}"

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


  
    
       {  ,  ,  ,   }
       
       
       

Component and Agent Presets

Presets are named configuration overrides defined within components, agents, or component templates. They allow the same codebase to run with different settings per environment.

Defining presets

Load golem-edit-manifest when adding or modifying preset sections in golem.yaml to ensure correct manifest structure.

Presets can be defined at the component template, component, or agent level:

componentTemplates:
  shared-runtime:
    env:
      RUST_LOG: info
    presets:
      local:
        default: true                # Used when no preset is explicitly selected
        env:
          GOLEM_ENV: local
      cloud:
        env:
          GOLEM_ENV: cloud

components:
  my-app:service:
    templates: shared-runtime
    dir: service
    presets:
      local:
        build:
          - command: cargo build --target wasm32-wasip1
      release:
        build:
          - command: cargo build --target wasm32-wasip1 --release

agents:
  MyAgent:
    env:
      CACHE_TTL: "300"
    presets:
      local:
        env:
          CACHE_TTL: "60"
      cloud:
        env:
          CACHE_TTL: 

What presets can override

Component presets can override: env, wasiConfig, plugins, files, config, build, componentWasm, outputWasm, customCommands, clean.

Agent presets can override: env, wasiConfig, plugins, files, config.

Presets cannot override structural fields like dir or templates.

How presets are activated

1. Via environments: The componentPresets field in an environment selects preset(s) by name:

   environments:
     local:
       componentPresets: local       # Activates "local" preset everywhere
     staging:
       componentPresets: [staging, debug]  # Multiple presets (applied in order)
   

2. Via CLI flag: The -P / --preset flag overrides environment preset selection:

   golem build --yes -P release
   golem deploy --yes -P debug,verbose
   

3. Default preset: One preset per component/agent/template can be marked default: true — it is used when no preset is explicitly selected by environment or CLI flag.

Naming guideline: Avoid using the same name for an environment and a preset (e.g. both called local). Although they are separate concepts, sharing names makes the manifest harder to read and reason about. Prefer distinct preset names such as dev, debug, release, or optimized that describe what the preset does, rather than mirroring the environment name.

Cascade with presets

Presets are the most specific layer in the cascade:

componentTemplates → components → agents → presets

Preset properties merge with or override the base properties using the same merge modes (envMergeMode, pluginsMergeMode, etc.).

Per-Agent Configuration

Configuration in the manifest is per agent. Each agent type can have its own:

• env — environment variables
• files — initial filesystem
• config — arbitrary typed configuration
• plugins — plugin installations

agents:
  EscalationAgent:
    env:
      MODEL: claude-3-7-sonnet
      JIRA_TOKEN: "{{ JIRA_TOKEN }}"
    files:
      - sourcePath: ./prompts/escalation-system.md
        targetPath: /prompts/system.md
    config:
      projectKey: OPS
      defaultPriority: high

  AuditAgent:
    env:
      S3_BUCKET: supportdesk-audit
    config:
      retentionDays: 90

Each agent can also have its own presets, allowing environment-specific overrides per agent type.

Common Patterns

Local development + cloud production

componentTemplates:
  shared:
    env:
      LOG_LEVEL: info
    presets:
      local:
        env:
          LOG_LEVEL: debug
      cloud:
        env:
          LOG_LEVEL: warn

environments:
  local:
    default: true
    server: local
    componentPresets: local
  prod:
    server: cloud
    componentPresets: cloud

Multiple staging environments

environments:
  local:
    default: true
    server: local
    componentPresets: local
  staging:
    server:
      url: https://staging.example.com
      auth:
        staticToken: "{{ STAGING_TOKEN }}"
    componentPresets: staging
  prod:
    account: my-org
    server: cloud
    componentPresets: prod

Profile without a manifest

When no golem.yaml is found, the CLI falls back to profiles:

golem profile new my-server --url https://my-server.example.com --static-token "..."
golem --profile my-server component list   # Use profile directly
golem -L component list                    # Use built-in "local" profile

Related Skills

• Load golem-edit-manifest for the complete manifest field reference
• Load golem-deploy for deployment commands and flags
• Load golem-deployment-version for per-environment version: overrides and the versionCheck uniqueness policy
• Load golem-add-env-vars for environment variable configuration details
• Load golem-add-initial-files for initial filesystem configuration