Configuration and Secrets

Before Golem 1.5, agents could only receive configuration through environment variables — string-only values that were not discoverable or type-checked. Golem 1.5 introduces code-first typed configuration and secrets that become part of an agent’s type. This means deployment can verify that all required configuration values are provided with proper types before the agent starts.

Configuration

Configuration types are defined as records in your agent’s source code and can be nested. They are injected via the agent’s constructor using the Config<T> wrapper type.

TypeScript


type DbConfig = { host: string, port: number }
type ExampleConfig = { debugLogs: boolean, alias?: string, database: DbConfig }
 
@agent()
class ExampleAgent extends BaseAgent {
  constructor(exampleParam: string, readonly config: Config<ExampleConfig>) { super(); }
 
  useConfig() {
    const config = this.config.value;
    if (config.debugLogs) {
      console.debug("Debug logs enabled");
    }
  }
}

Rust


#[derive(ConfigSchema)]
pub struct DbConfig {
    host: String,
    port: u16,
}
 
#[derive(ConfigSchema)]
pub struct ExampleConfig {
    debug_logs: bool,
    alias: Option<String>,
    database: DbConfig,
}
 
#[agent_definition]
pub trait ExampleAgent {
    fn new(name: String, #[agent_config] config: Config<ExampleConfig>) -> Self;
    fn use_config(&self);
}

Scala


final case class DbConfig(host: String, port: Int)
object DbConfig {
  implicit val schema: Schema[DbConfig] = Schema.derived
}
 
final case class ExampleConfig(debugLogs: Boolean, alias: Option[String], database: DbConfig)
object ExampleConfig {
  implicit val schema: Schema[ExampleConfig] = Schema.derived
}
 
@agentDefinition()
trait ExampleAgent extends BaseAgent with AgentConfig[ExampleConfig] {
  class Id(val exampleParam: String)
  def useConfig(): Future[Unit]
}

MoonBit


#derive.config
pub(all) struct DbConfig {
  host: String,
  port: UInt,
}
 
#derive.config
pub(all) struct ExampleConfig {
  debug_logs: Bool,
  alias: String?,
  database: DbConfig,
}

Providing configuration in golem.yaml

Configuration values are specified in golem.yaml under the config section for each agent:


agents:
  ExampleAgent:
    config:
      debugLogs: true
      database:
        host: localhost
        port: 5432

Secrets

Secrets are a special type of configuration — they are stored per environment and can be updated dynamically without redeploying the agent. To mark a configuration field as a secret, wrap its type in Secret<T>:

TypeScript


password: Secret<string>

Rust


#[config_schema(secret)]
password: Secret<String>,

Scala


password: Secret[String]

MoonBit


password: @config.Secret[String]

Accessing secrets

Unlike regular configuration values, secrets must be retrieved by calling .get() on the Secret field. This ensures you always get the latest value, even if the secret has been updated since the agent started.

Managing secrets via CLI

Use the golem agent-secret CLI commands to manage secrets:


golem agent-secret create db.password --secret-type string --secret-value "pwd"
golem agent-secret list
golem agent-secret update-value db.password --secret-value "new-pwd"
golem agent-secret delete db.password

Secret defaults in golem.yaml

You can define default secret values per environment in golem.yaml. The {{ X }} syntax resolves environment variables from the user’s system at deploy time:


secretDefaults:
  local:
    - path: [db, password]
      value: "{{ DB_PASSWORD }}"