gutsofpratik/horizon-skills/source-0df8b3d367c71ce9f4533adc

Credentials as Environment Variables

When to Use This Skill

• Setting up ANTHROPIC_API_KEY or OPENAI_API_KEY from encrypted credentials
• Wiring any credential path to a process.env variable automatically
• Migrating from plaintext .env secrets to encrypted credentials
• Understanding why an env var is being resolved at worker startup

The credential: Convention

Any env var whose value starts with credential: is resolved from encrypted credentials at worker startup. The format is:

ENV_VAR_NAME=credential:<dot.path>

Example .env

# These are resolved automatically from the global credentials
ANTHROPIC_API_KEY=credential:anthropic.api_key
OPENAI_API_KEY=credential:openai.api_key
 
# Any credential path works
MY_SERVICE_TOKEN=credential:my_service.token
DATABASE_URL=credential:postgres.url

Encrypted credentials (config/credentials.yml.enc)

anthropic:
  api_key: sk-ant-...        # → resolves ANTHROPIC_API_KEY
 
openai:
  api_key: sk-...            # → resolves OPENAI_API_KEY
 
my_service:
  token: tok_live_...        # → resolves MY_SERVICE_TOKEN
 
postgres:
  url: postgres://...        # → resolves DATABASE_URL

How It Works

When the worker starts, every env var set to credential:<path> is replaced with the decrypted value at that path. By the time a workflow runs, ANTHROPIC_API_KEY holds the real key and LLM SDKs read it as usual.

Values come from the global credentials for the current environment: config/credentials/<NODE_ENV>.yml.enc when it exists, otherwise config/credentials.yml.enc. Workflow-scoped credentials are never used for env vars, so keep these paths in the global file.

Precedence Rules

Real env var values always take precedence. If ANTHROPIC_API_KEY is already set to a non-credential: value (e.g. from the shell or a CI secret), it is never overwritten:

# Real value - never replaced
ANTHROPIC_API_KEY=sk-ant-real-override
 
# Placeholder — gets replaced at startup
ANTHROPIC_API_KEY=credential:anthropic.api_key

This means you can override any credential ref at deploy time without changing files.

Setting Up the Convention

Step 1: Initialize credentials (if not done)

npx output credentials init
npx output credentials edit   # Add anthropic.api_key, openai.api_key

Step 2: Update .env

# Replace plaintext secrets with credential references
ANTHROPIC_API_KEY=credential:anthropic.api_key
OPENAI_API_KEY=credential:openai.api_key

Step 3: Verify

Start the worker and look for the log line:

[info] Credentials: Resolved credential env vars { vars: [ "ANTHROPIC_API_KEY", "OPENAI_API_KEY" ] }

If the log line lists your env vars, credentials are wired correctly.

Verification Checklist

• [ ] config/credentials.yml.enc contains the target credential paths
• [ ] .env uses credential:<path> values for the relevant env vars
• [ ] Worker startup log shows Resolved credential env vars listing the expected env vars
• [ ] First LLM workflow run succeeds (confirming ANTHROPIC_API_KEY is set correctly)
• [ ] Setting a real env var in the shell overrides the credential ref

Related Skills

• output-credentials-init — Create the encrypted credentials file
• output-credentials-edit — Add/update credential values
• output-dev-credentials — Full credentials system reference