Adding Secrets to a Scala Golem Agent

Overview

Secrets are sensitive configuration values (API keys, passwords, tokens) stored per-environment and accessed via Secret[T] from golem.config. They are declared inside config case classes alongside regular config fields, but the config value carries an opaque secret handle; plaintext is revealed only when agent code calls .get.

Declaring Secrets

Wrap sensitive fields with Secret[T] in your config case class. Secret[T] has an implicit Schema derivation, so Schema.derived works automatically on parent case classes:

import golem.config.Secret
import zio.blocks.schema.Schema

final case class DbConfig(
  host: String,
  port: Int,
  password: Secret[String],
)

object DbConfig {
  implicit val schema: Schema[DbConfig] = Schema.derived
}

final case class MyAppConfig(
  appName: String,
  apiKey: Secret[String],
  db: DbConfig,
)

object MyAppConfig {
  implicit val schema: Schema[MyAppConfig] = Schema.derived
}

Reading Secrets

Secret[T] is lazy — call .get to explicitly reveal the current value:

import golem.runtime.annotations.agentImplementation
import golem.config.Config

import scala.concurrent.Future

@agentImplementation()
final class MyAgentImpl(input: String, config: Config[MyAppConfig]) extends MyAgent {
  override def connect(): Future[String] = {
    val cfg = config.value
    val key = cfg.apiKey.get
    val pwd = cfg.db.password.get
    Future.successful(s"Connected to ${cfg.db.host}:${cfg.db.port}")
  }
}

Managing Secrets via CLI

Secret paths use camelCase, matching Scala field names:

golem secret create apiKey --type String --value "sk-abc123"
golem secret create db.password --type String --value "s3cret"
printenv DB_PASSWORD | golem secret create db.password --type String --value-stdin
golem secret create apiKey --type String --value "sk-abc123" --update-existing
golem secret list
golem secret update apiKey --value "new-value"
golem secret update apiKey --unset
golem secret delete apiKey

Note: Without a value option, create and update prompt for the value (hidden input). --update-existing updates the value of an existing secret instead of failing. delete asks for confirmation (--yes skips it). For update and delete, you can also use --id <uuid> instead of the positional path.

Secret Defaults in golem.yaml

Use secretDefaults for local development only — manage production secrets via CLI:

secretDefaults:
  local:
    apiKey: "dev-key-123"
    db:
      password: "dev-password"

Key Constraints

• Secret[T] is lazy — call .get to reveal the actual value
• Each reveal pins the resolved secret revision for deterministic retries and replay; fresh .get calls can observe runtime updates
• Secret values are stored per-environment, not per-agent-instance
• The Secret[T] companion provides an implicit Schema so Schema.derived works on parent case classes
• Missing required secrets cause agent creation to fail
• Secret paths use camelCase (matching Scala field names)
• The --type argument accepts Scala type names: String, Int, Boolean, List[String], Option[Int] (if parsing as Scala fails, the other supported languages' type syntax is tried)
• Use secretDefaults in golem.yaml only for development; manage production secrets via CLI
• If the agent also needs non-secret typed config guidance, use golem-add-config-scala alongside this skill