Secrets providers

Secrets providers resolve ref URIs into runtime values for Loom jobs. Each provider handles a specific URI scheme. This page helps you choose a provider and find the setup documentation.

Choosing a provider

Need	Recommended provider	Why
Quick migration from existing env-based secret delivery	Environment (env://)	Zero setup — reads values already in the host environment
Local encrypted storage without external services	KeePass (keepass://)	Offline .kdbx vaults with alias-driven configuration
Team/shared vault with access control and audit logging	1Password (op://)	Centralized vaults via service account tokens and the 1Password Go SDK

Provider matrix

Provider	URI scheme	Auth requirement	Status
Environment passthrough	env://<VAR_NAME>	None (reads host process env)	Implemented
KeePass	keepass://<database-alias>#<path>:<field>	Alias-based runtime config (LOOM_KEEPASS_DB_<ALIAS>_*)	Implemented
1Password	op://<vault>/<item>/<field>	OP_SERVICE_ACCOUNT_TOKEN in runtime env	Implemented

Provider contract

All providers follow the same behavioral contract:

• Resolve only declared job secrets — providers receive only the refs declared on the current job, not the full workflow.
• Direct injection flow — resolved bytes return to the injection pipeline, which writes a Loom-managed temp file by default or places the raw value in the environment for file: false.
• Deterministic error codes — failures produce SECRETS_* error codes with non-sensitive diagnostic messages.
• Redaction — Loom registers each resolved value for exact-match redaction in its supported text outputs. Transformed values and raw declared artifact contents are not inspected.
• Required secrets — missing or invalid credentials fail the job when the secret is required (the default). An unresolved required: false secret is omitted from injection and the job continues; Loom does not substitute another provider.

Environment (env://)

The environment provider reads a value from the Loom runtime process environment. No additional setup or auth is required.

URI format:

env://<VARIABLE_NAME>

Example:

deploy:
  secrets:
    DEPLOY_TOKEN:
      ref: env://DEPLOY_TOKEN_VALUE

When to use: Migrating from existing CI systems that inject secrets as environment variables, or wrapping secrets already managed by your runner infrastructure.

Limitation: The host environment may be broadly scoped. Values are visible to child processes and unrelated tooling running in the same session.

KeePass (keepass://)

The KeePass provider resolves secrets from local encrypted .kdbx databases using alias-driven runtime configuration.

URI format:

keepass://<database-alias>#<entry-path>:<field>

Setup and usage:

• Overview — URI format, resolution flow, and failure codes
• Install and setup — prerequisites and database configuration
• CLI commands — manage databases, entries, and fields
• Workflows — use KeePass secrets in workflow files

1Password (op://)

The 1Password provider resolves secrets from 1Password vaults using the Go SDK. No op CLI binary is required.

URI format:

op://<vault>/<item>/<field>

Setup and usage:

• Overview — URI format, resolution flow, and failure codes
• Install and setup — prerequisites, service account auth, and validation
• CLI commands — list vaults and items, create and rotate fields

Security considerations

Before enabling any provider in production workflows:

• Review the Secrets security page for the full threat model and provider-specific risk profiles.
• Follow the operational guardrails for production configuration.
• See the Secrets overview for injection modes, error codes, and scoping rules.