Skip to main content

​
Overview

The fastagent.secrets.yaml file provides a secure way to store API keys, tokens, and other sensitive configuration separate from your main configuration file. This allows you to commit fastagent.config.yaml to version control while keeping secrets out of your repository.
Always add fastagent.secrets.yaml to your .gitignore file to prevent accidentally committing secrets to version control.

​
File Discovery

Fast Agent recursively searches for fastagent.secrets.yaml from your current directory upward, so you only need to manage this file at the root of your project or workspace. Search priority:
  1. Same directory as fastagent.config.yaml (if found)
  2. Recursive search from current directory upward
You can place fastagent.secrets.yaml at your workspace root and all nested projects will automatically discover and use it.

​
Basic Structure

The secrets file follows the same structure as the main configuration file, but typically contains only sensitive values: 
anthropic:
  api_key: "sk-ant-xxxxxxxxxxxxx"

openai:
  api_key: "sk-xxxxxxxxxxxxxxxxx"

google:
  api_key: "AIzaXXXXXXXXXXXXXXXXXX"

​
Provider API Keys

​
Anthropic

anthropic:
  api_key: "sk-ant-xxxxxxxxxxxxx"

​
OpenAI

openai:
  api_key: "sk-xxxxxxxxxxxxxxxxx"

​
Google (Gemini)

google:
  api_key: "AIzaXXXXXXXXXXXXXXXXXX"
For Vertex AI: 
google:
  vertex_ai:
    enabled: true
    project_id: "my-project-id"
    location: "us-central1"

​
DeepSeek

deepseek:
  api_key: "sk-xxxxxxxxxxxxx"

​
xAI (Grok)

xai:
  api_key: "xai-xxxxxxxxxxxxx"

​
Azure OpenAI

azure:
  api_key: "xxxxxxxxxxxxxxxxxxxxx"
  resource_name: "your-resource-name"

​
AWS Bedrock

bedrock:
  region: "us-east-1"
  profile: "default"  # AWS profile name
Bedrock uses AWS credentials from your AWS CLI configuration or environment variables. The profile setting references your AWS credentials profile.

​
Groq

groq:
  api_key: "gsk_xxxxxxxxxxxxx"

​
HuggingFace

huggingface:
  api_key: "hf_xxxxxxxxxxxxx"  # HF_TOKEN

​
OpenRouter

openrouter:
  api_key: "sk-or-xxxxxxxxxxxxx"

​
TensorZero

tensorzero:
  api_key: "tz-xxxxxxxxxxxxx"

​
MCP Server Secrets

​
Environment Variables for MCP Servers

mcp:
  servers:
    brave:
      env:
        BRAVE_API_KEY: "BSAxxxxxxxxxxxxx"
    
    github:
      env:
        GITHUB_TOKEN: "ghp_xxxxxxxxxxxxx"
    
    custom_api:
      env:
        API_KEY: "xxxxxxxxxxxxx"
        API_SECRET: "xxxxxxxxxxxxx"

​
Custom Headers with Secrets

mcp:
  servers:
    api_server:
      headers:
        "Authorization": "Bearer xxxxxxxxxxxxx"
        "X-API-Key": "xxxxxxxxxxxxx"

​
Environment Variable Substitution

Instead of storing secrets in files, you can reference environment variables:

​
In fastagent.config.yaml

anthropic:
  api_key: "${ANTHROPIC_API_KEY}"

openai:
  api_key: "${OPENAI_API_KEY}"

mcp:
  servers:
    brave:
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"

​
With Default Values

openai:
  api_key: "${OPENAI_API_KEY:sk-default-key}"
This uses the environment variable if set, otherwise falls back to the default value.

​
Combined Configuration Example

​
fastagent.config.yaml (committed to git)

default_model: gpt-5-mini.low

logger:
  type: file
  level: error

anthropic:
  api_key: "${ANTHROPIC_API_KEY}"  # Reference env var
  default_model: "claude-3-5-sonnet-20241022"

openai:
  api_key: "${OPENAI_API_KEY}"  # Reference env var
  default_model: "gpt-5-mini"

mcp:
  targets:
    - name: fetch
      target: "uvx mcp-server-fetch"
    
    - name: brave
      target: "npx -y @modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"  # Reference env var

​
fastagent.secrets.yaml (not committed to git)

# API Keys for LLM Providers
anthropic:
  api_key: "sk-ant-xxxxxxxxxxxxx"

openai:
  api_key: "sk-xxxxxxxxxxxxxxxxx"

google:
  api_key: "AIzaXXXXXXXXXXXXXXXXXX"

# MCP Server Credentials
mcp:
  servers:
    brave:
      env:
        BRAVE_API_KEY: "BSAxxxxxxxxxxxxx"

​
.gitignore

# Fast Agent secrets
fastagent.secrets.yaml

# Environment variables
.env
.env.local

# Fast Agent runtime directory
.fast-agent/

​
Secrets Precedence

When the same key exists in multiple locations, the precedence order is:
  1. Environment variables: Highest priority
  2. fastagent.secrets.yaml: Overrides config file
  3. fastagent.config.yaml: Default values
Example: 
# fastagent.config.yaml
openai:
  api_key: "default-key"
  default_model: "gpt-4.1"

# fastagent.secrets.yaml  
openai:
  api_key: "secret-key"  # Overrides config file

# Environment variable (highest priority)
export OPENAI_API_KEY="env-key"  # Overrides everything
Final result: api_key = "env-key", default_model = "gpt-4.1"

​
Complete Secrets Example

# fastagent.secrets.yaml
# DO NOT COMMIT THIS FILE TO VERSION CONTROL

# LLM Provider API Keys
anthropic:
  api_key: "sk-ant-api03-xxxxxxxxxxxxx"

openai:
  api_key: "sk-proj-xxxxxxxxxxxxx"

google:
  api_key: "AIzaSyXXXXXXXXXXXXXXXX"
  vertex_ai:
    enabled: true
    project_id: "my-gcp-project"
    location: "us-central1"

deepseek:
  api_key: "sk-xxxxxxxxxxxxx"

xai:
  api_key: "xai-xxxxxxxxxxxxx"

azure:
  api_key: "xxxxxxxxxxxxx"
  resource_name: "my-azure-resource"
  azure_deployment: "gpt-4"
  api_version: "2023-05-15"

groq:
  api_key: "gsk_xxxxxxxxxxxxx"

huggingface:
  api_key: "hf_xxxxxxxxxxxxx"

openrouter:
  api_key: "sk-or-xxxxxxxxxxxxx"

# MCP Server Environment Variables
mcp:
  servers:
    brave:
      env:
        BRAVE_API_KEY: "BSAxxxxxxxxxxxxx"
    
    github:
      env:
        GITHUB_TOKEN: "ghp_xxxxxxxxxxxxx"
    
    anthropic_api:
      headers:
        "Authorization": "Bearer xxxxxxxxxxxxx"
    
    custom_service:
      env:
        SERVICE_API_KEY: "xxxxxxxxxxxxx"
        SERVICE_SECRET: "xxxxxxxxxxxxx"

# OpenTelemetry (if using authenticated endpoint)
otel:
  http_headers:
    "Authorization": "Bearer xxxxxxxxxxxxx"

​
Best Practices

Secrets Management Best Practices

  1. Never commit secrets to version control
    • Add fastagent.secrets.yaml to .gitignore
    • Use placeholder values in example files
  2. Use environment variables for CI/CD
    • Reference ${ENV_VAR} in config files
    • Set secrets in your CI/CD platform
  3. Scope secrets appropriately
    • Store provider keys in provider sections
    • Store MCP server secrets under mcp.servers
  4. Rotate secrets regularly
    • Generate new API keys periodically
    • Update secrets file and environment variables
  5. Document required secrets
    • Provide fastagent.secrets.yaml.example template
    • List required environment variables in README
  6. Use least privilege
    • Request minimum required API scopes
    • Create separate keys for different environments

​
Secrets Template

Create a fastagent.secrets.yaml.example file in your repository as a template: 
# fastagent.secrets.yaml.example
# Copy this file to fastagent.secrets.yaml and fill in your actual secrets

anthropic:
  api_key: "sk-ant-YOUR_KEY_HERE"

openai:
  api_key: "sk-YOUR_KEY_HERE"

mcp:
  servers:
    brave:
      env:
        BRAVE_API_KEY: "YOUR_BRAVE_API_KEY"
Users can copy and populate this file: 
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
# Edit fastagent.secrets.yaml with actual secrets

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us