Secrets

Store credentials once, encrypted at rest, and inject them into replayed agents through agent version run specs.

A replayed agent needs the same credentials the original had, such as a model provider key or a database URL. You could bake them into every worker's environment; secrets are the managed alternative: named bundles of key-value pairs, stored encrypted on the server (KITARU_SERVER_SECRET_ENCRYPTION_KEY), and injected into agent subprocesses at run time.

Create a secret

from kitaru.api_models.v1.secret import SecretCreateRequest

secret = await client.secrets.create(
    SecretCreateRequest(
        name="openai",
        values={"OPENAI_API_KEY": "sk-..."},
    )
)

Values are write-mostly: listings and gets return metadata only unless you explicitly request values (include_values), and updates replace the value map wholesale.

Attach it to an agent version

Reference secrets when registering the version. Each key in the secret becomes an environment variable of the replayed agent's process:

kitaru agent register support-agent \
  --command "python support.py" \
  --secret-id <openai-secret-id>

When a worker runs a replay for that version, it fetches the referenced secrets and layers them onto the subprocess environment, after the version's own --env entries, with later secrets winning on key collisions. The worker's own KITARU_API_URL/KITARU_API_KEY can never be overridden by a secret.

What secrets don't cover (yet)

Evaluator plugins run without a run spec, so they don't receive per-plugin secrets. An LLM-judge evaluator reads its provider key from the worker's environment. Put judge credentials in the environment of the workers that run evaluations. Per-plugin secret references for evaluators are on the roadmap.

Importer plugins are the exception: a provider connection holds an importer's credentials on the server and delivers them to whichever worker claims the import task, so an importer's own key does not need to live in every worker's environment the way a judge's does.

Rotation is an update plus nothing else: the next task fetches the new values. Nothing caches decrypted secrets on disk.