How to Configure Groq and OpenAI API Keys for Agent Reach Podcast Transcription

Use agent-reach configure groq-key <key> or agent-reach configure openai-key <key> to store API keys in ~/.agent-reach/config.yaml, or set the GROQ_API_KEY and OPENAI_API_KEY environment variables for containerized deployments.

Agent Reach's transcription feature converts podcast audio to text using Whisper models from Groq (free tier) or OpenAI (paid tier). According to the Panniantong/Agent-Reach source code, the CLI supports both providers through a unified configuration system that validates credentials against a feature requirements schema before initiating transcription.

Where API Keys Are Defined

The transcription system declares its credential requirements in agent_reach/config.py. The FEATURE_REQUIREMENTS dictionary maps each provider to its required API key:

FEATURE_REQUIREMENTS = {
    "groq_whisper": ["groq_api_key"],
    "openai_whisper": ["openai_api_key"],
    ...
}

This schema resides at lines 24-29 in agent_reach/config.py and drives the validation logic used by both the configuration commands and the transcription runtime.

How to Configure the Keys

Method 1: CLI Configuration (Recommended)

The agent-reach configure command writes credentials to ~/.agent-reach/config.yaml. According to agent_reach/cli.py (lines 1126-1132), the CLI handles two specific sub-commands:

# Configure Groq (free whisper-large-v3)

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

# Configure OpenAI (paid whisper-1)

agent-reach configure openai-key sk-XXXXXXXXXXXXXXXXXXXXXXXX

When executed, the CLI updates the config file:

elif args.key == "groq-key":
    config.set("groq_api_key", value)
    print("✅ Groq key configured!")
elif args.key == "openai-key":
    config.set("openai_api_key", value)
    print("✅ OpenAI key configured!")

Method 2: Environment Variables

For CI/CD pipelines or Docker containers, export the keys as environment variables. The Config.get method checks these after the config file, allowing environment variables to override or supplement the YAML storage:

export GROQ_API_KEY=gsk_XXXXXXXXXXXXXXXX
export OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX

The transcription logic in agent_reach/transcribe.py retrieves these values through the _provider_key helper function (lines 107-111), which queries the config object and falls back to environment variables.

Verification

Validate your configuration using the built-in health check:

agent-reach doctor

A green checkmark appears next to "Groq API key configured" or "OpenAI API key configured" when the credentials are properly stored.

Using the Transcription Feature

Once keys are configured, the transcribe command automatically selects Groq first (free tier), falling back to OpenAI on failure. The runtime logic in agent_reach/transcribe.py (lines 24-28) calls _provider_key() to retrieve the appropriate credential before sending audio chunks to the Whisper endpoint.

Automatic Provider Selection

Run transcription without specifying a provider:

agent-reach transcribe https://example.com/podcast.mp3

Force a Specific Provider

Override the default preference using the --provider flag:

# Explicitly use Groq

agent-reach transcribe https://example.com/podcast.mp3 --provider groq

# Explicitly use OpenAI

agent-reach transcribe https://example.com/podcast.mp3 --provider openai

Save Output to File

Capture transcripts to a local file with the -o flag:

agent-reach transcribe https://example.com/podcast.mp3 -o transcript.txt

Summary

• Agent Reach stores transcription API keys in ~/.agent-reach/config.yaml under the fields groq_api_key and openai_api_key
• Use agent-reach configure groq-key <key> and agent-reach configure openai-key <key> to persist credentials via the CLI
• Environment variables GROQ_API_KEY and OPENAI_API_KEY override config file values, ideal for containerized environments
• The transcription feature defaults to Groq's free whisper-large-v3 model, falling back to OpenAI's whisper-1 when necessary
• Configuration validation is available through the agent-reach doctor command

Frequently Asked Questions

Can I use both Groq and OpenAI keys simultaneously?

Yes. Agent Reach supports storing both keys in the configuration file. The transcription command defaults to Groq for cost efficiency but automatically falls back to OpenAI if the Groq request fails or if Groq rate limits are exceeded. You can also force a specific provider with the --provider flag.

Where does Agent Reach store the API keys locally?

The CLI writes API keys to ~/.agent-reach/config.yaml in your home directory. This YAML file maintains the groq_api_key and openai_api_key fields that the transcription subsystem reads at runtime. If this file is missing or corrupted, the CLI will recreate it on the next configure command.

What happens if I don't configure any API keys?

If neither GROQ_API_KEY nor OPENAI_API_KEY is set, and the config file lacks these values, the transcription command will fail with an authentication error. The agent-reach doctor command identifies missing credentials before you attempt transcription, reporting which provider keys are missing from your environment.

Is Groq truly free for podcast transcription?

According to the Agent Reach source code, Groq provides free access to the whisper-large-v3 model, making it the default provider for cost optimization. OpenAI's whisper-1 model requires a paid API key. Both implement the same underlying Whisper architecture, though Groq's free tier may have rate limits that trigger the automatic OpenAI fallback during high-volume usage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}