Secrets Management

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:

Same directory as fastagent.config.yaml (if found)
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:

Environment variables: Highest priority
fastagent.secrets.yaml: Overrides config file
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