Credentials

AI apps need a lot of API keys, database passwords, and third-party tokens. Sharing .env files is risky, and coding agents shouldn’t see your secrets. The credentials system keeps these secrets encrypted at rest in your repository as YAML files that you commit alongside your code — no external vault subscription needed. At runtime, a single encryption key decrypts everything. Each workflow can have its own scoped credentials that override shared defaults, giving you both team-wide consistency and per-workflow flexibility. You manage credentials through the CLI and read them in your steps with a simple dot-notation API.

Setting Up Credentials

Initialize credentials for your project:

output credentials init

This generates two files:

config/credentials.key — your 256-bit encryption key (never commit this)
config/credentials.yml.enc — the encrypted YAML file (safe to commit)

Add your secrets by opening the encrypted file in your editor:

output credentials edit

The CLI decrypts the file, opens it in $EDITOR, and re-encrypts when you save. Fill in your secrets:

# config/credentials.yml.enc (decrypted view)
anthropic:
  api_key: sk-ant-xxxxx
openai:
  api_key: sk-xxxxx
stripe:
  secret_key: sk_live_xxxxx

Then read them in any step:

// src/workflows/billing/steps.ts
import { step, z } from '@outputai/core';
import { credentials } from '@outputai/core/credentials';

export const chargeCustomer = step({
  name: 'chargeCustomer',
  inputSchema: z.object({ customerId: z.string(), amount: z.number() }),
  outputSchema: z.object({ chargeId: z.string() }),
  fn: async (input) => {
    const stripeKey = credentials.require('stripe.secret_key');
    // use stripeKey to call the Stripe API...
  }
});

credentials.require() throws a MissingCredentialError if the path doesn’t exist. Use credentials.get(path, defaultValue) when you want a safe fallback instead:

const region = credentials.get('aws.region', 'us-east-1');

Wiring LLM Keys to Environment Variables

LLM SDKs like the Anthropic and OpenAI clients read their API keys from environment variables. Rather than duplicating these keys in both your .env file and your encrypted credentials, you can wire credentials directly into environment variables using the credential: prefix. In your .env file, set the variable to credential:<dot.path> instead of the actual key:

# .env
ANTHROPIC_API_KEY=credential:anthropic.api_key
OPENAI_API_KEY=credential:openai.api_key

When the worker starts, every env var set to credential:<path> is replaced with the value at that path in 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 not used for env vars. By the time your first workflow runs, ANTHROPIC_API_KEY contains the real key — no code changes needed. The worker logs confirmation on startup:

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

Real environment variable values are never overwritten. If ANTHROPIC_API_KEY is already set in the shell or injected by your CI/CD pipeline, the credential reference is ignored. This gives you a safe override path for production deployments without touching files.

Scoping Credentials to Environments

You likely need different API keys for development and production. The credentials system supports environment-specific files that sit alongside the global defaults:

# Initialize production credentials
output credentials init --environment production

# Initialize development credentials
output credentials init --environment development

This creates a config/credentials/ directory with per-environment files:

config/
├── credentials.yml.enc              # Global (shared defaults)
├── credentials.key                  # Global key
└── credentials/
    ├── production.yml.enc           # Production overrides
    ├── production.key               # Production key
    ├── development.yml.enc          # Development overrides
    └── development.key              # Development key

At runtime, the system checks NODE_ENV and loads the matching environment file. Only "production" and "development" are recognized — other values fall back to the global file. Edit environment-specific credentials the same way:

output credentials edit --environment production

Scoping Credentials to Workflows

Sometimes a single workflow needs its own secrets — a dedicated API key with different permissions, or a third-party token that only one workflow uses. You can scope credentials to a specific workflow:

output credentials init --workflow payment_processing

This creates credentials files inside the workflow directory:

src/workflows/payment_processing/
├── workflow.ts
├── steps.ts
├── credentials.yml.enc             # Workflow-specific secrets
└── credentials.key                 # Workflow-specific key

When a step runs inside this workflow, its credentials are deep-merged over the global ones. Workflow values win at the same path; global values fill in the rest. Global credentials:

anthropic:
  api_key: sk-ant-global
aws:
  region: us-east-1
  secret: aws-global-secret

Workflow credentials (payment_processing):

anthropic:
  api_key: sk-ant-workflow-specific
stripe:
  secret_key: sk_live_workflow

What credentials.get() sees inside the workflow:

anthropic:
  api_key: sk-ant-workflow-specific   # Overridden by workflow
aws:
  region: us-east-1                   # From global
  secret: aws-global-secret           # From global
stripe:
  secret_key: sk_live_workflow        # Added by workflow

--environment and --workflow are mutually exclusive flags. Environment scoping applies at the global level; workflow scoping applies per-workflow.

Deploying to Production

In local development, the .key files on disk handle decryption. In production, CI/CD, and Docker — where you don’t have key files — set the decryption key as an environment variable. The system resolves keys with a fallback chain:

Scope	Environment Variable	Key File
Global	`OUTPUT_CREDENTIALS_KEY`	`config/credentials.key`
Environment	`OUTPUT_CREDENTIALS_KEY_PRODUCTION`	`config/credentials/production.key`
Workflow	`OUTPUT_CREDENTIALS_KEY_PAYMENT_PROCESSING`	`src/workflows/payment_processing/credentials.key`

The resolution order is: environment variable first, then key file. Workflow keys fall back to the global key if neither a workflow-specific env var nor a key file is found.

Docker

The encrypted credentials file must be present in the image — the key alone isn’t enough. Make sure your Dockerfile includes:

COPY config/ ./config/

The config/ directory is not cleaned up after the build because the encrypted file is read at runtime, not build time. Pass the decryption key as an environment variable in your Docker Compose or container config:

# docker-compose.yml
services:
  worker:
    image: your-worker-image
    environment:
      - OUTPUT_CREDENTIALS_KEY=${OUTPUT_CREDENTIALS_KEY}
      - NODE_ENV=production

CI/CD

Store the key in your CI provider’s secrets and expose it as an environment variable:

# GitHub Actions example
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      OUTPUT_CREDENTIALS_KEY: ${{ secrets.OUTPUT_CREDENTIALS_KEY }}
      OUTPUT_CREDENTIALS_KEY_PRODUCTION: ${{ secrets.OUTPUT_CREDENTIALS_KEY_PRODUCTION }}
    steps:
      - run: output workflow run my_workflow

Key Management

Never commit key files

Add this to your .gitignore:

# Credential encryption keys
*.key

The encrypted .yml.enc files are safe to commit — they can’t be decrypted without the key. Key files are created with 0o600 permissions (owner read/write only). Share keys with teammates through a secure channel — a password manager, encrypted messaging, or your organization’s secret sharing tool. Each developer needs the key file at the expected path, or the matching environment variable set.

Rotating keys

To rotate a key:

Decrypt your current credentials: output credentials show > /tmp/creds.yml
Re-initialize with --force to generate a new key: output credentials init --force
Edit and paste your secrets back: output credentials edit
Distribute the new key to your team and update environment variables in production
Securely delete the temporary file: rm /tmp/creds.yml

Verifying credentials

Use the CLI to check that credentials are correctly set up:

# Show all decrypted credentials
output credentials show

# Get a specific value
output credentials get anthropic.api_key

# Check a workflow's credentials
output credentials get stripe.secret_key --workflow payment_processing

Custom Providers

The default provider reads encrypted YAML files from disk. You can replace it with a custom provider for alternative backends (e.g., AWS Secrets Manager, HashiCorp Vault) using setProvider():

import { setProvider } from '@outputai/core/credentials';
import type { CredentialsProvider } from '@outputai/core/credentials';

const vaultProvider: CredentialsProvider = {
  loadGlobal: ({ environment }) => {
    // Return credentials as a plain object
    return { anthropic: { api_key: fetchFromVault('anthropic-key') } };
  },
  loadForWorkflow: ({ workflowName, workflowDir, environment }) => {
    // Return workflow-specific credentials, or null to use global only
    return null;
  }
};

setProvider(vaultProvider);

Call setProvider() in a hook file listed under outputai.hookFiles. Hook files load before the worker resolves credential: env vars, so those resolve through your provider too.

Method	Arguments	Returns
`loadGlobal(context)`	`{ environment: string \| undefined }`	`Record<string, unknown>`
`loadForWorkflow(context)`	`{ workflowName: string, workflowDir: string \| undefined, environment?: string }`	`Record<string, unknown> \| null`

Returning null from loadForWorkflow means the workflow has no overrides, so global credentials are used as-is.

Security

Credentials are encrypted with AES-256-GCM using the @noble/ciphers library. Each encryption uses a fresh random nonce, so the same plaintext produces different ciphertext every time.

Key files are created with file mode 0o600 (owner read/write only).
During output credentials edit, the temporary plaintext file is overwritten with null bytes before it is deleted.

API Reference

import {
  credentials,
  setProvider,
  MissingCredentialError, MissingKeyError, InvalidCredentialsKeyError, MalformedCredentialsKeyError
} from '@outputai/core/credentials';
import type { CredentialsProvider } from '@outputai/core/credentials';

Method	Returns	Throws
`credentials.get(path, defaultValue?)`	The value at `path`, or `defaultValue` (default `undefined`) when missing	Never for a missing path
`credentials.require(path)`	The value at `path`	`MissingCredentialError` when the value is missing or `null`

path is a dot-notation path into the decrypted YAML, e.g. 'anthropic.api_key'. Inside a step, the workflow’s credentials are merged over the global ones. Credentials are decrypted once per scope and cached for the life of the process.

Errors

All four errors extend FatalError, so a step that throws one fails without being retried.

Error	Thrown when
`MissingCredentialError`	`credentials.require()` finds no value at the path
`MissingKeyError`	No decryption key is found in the env var or key file
`InvalidCredentialsKeyError`	The key can’t decrypt the file: it doesn’t match, or the file is corrupted
`MalformedCredentialsKeyError`	The key isn’t exactly 64 hex characters

For complete TypeScript API documentation, see the Credentials Module API Reference.

Start Here

Workflows

Steps

Prompts

Clients

Costs

Evaluators

Production Readiness

Deployment

Integrate with Your App

Packages

Releases

Credentials

Setting Up Credentials

Wiring LLM Keys to Environment Variables

Scoping Credentials to Environments

Scoping Credentials to Workflows

Deploying to Production

Docker

CI/CD

Key Management

Never commit key files

Rotating keys

Verifying credentials

Custom Providers

Security

API Reference

credentials

Errors

​Setting Up Credentials

​Wiring LLM Keys to Environment Variables

​Scoping Credentials to Environments

​Scoping Credentials to Workflows

​Deploying to Production

​Docker

​CI/CD

​Key Management

​Never commit key files

​Sharing keys with your team

​Rotating keys

​Verifying credentials

​Custom Providers

​Security

​API Reference

​credentials

​Errors

Setting Up Credentials

Wiring LLM Keys to Environment Variables

Scoping Credentials to Environments

Scoping Credentials to Workflows

Deploying to Production

Docker

CI/CD

Key Management

Never commit key files

Sharing keys with your team

Rotating keys

Verifying credentials

Custom Providers

Security

API Reference

credentials

Errors