How to Force a Specific Backend in Agent Reach: Environment Variables and Config Keys

Set the <CHANNEL>_BACKEND environment variable or add a <channel>_backend key to ~/.agent-reach/config.yaml to prioritize a specific backend for any channel.

Agent Reach is an open-source automation framework that selects backends dynamically from each channel's candidate list. You can override this selection order using configuration files or environment variables to force a specific backend without modifying the core source code.

How Backend Selection Works

Agent Reach selects a backend by iterating through the channel's backends list and probing each one until a working connection is established. The framework provides two mechanisms to reorder this list and force a preferred backend to the front.

The logic resides in two critical components:

• Channel.ordered_backends() – Reorders the candidate list according to override preferences. Located in [agent_reach/channels/base.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py#L45-L59).
• Config.get() – Retrieves configuration values from the YAML file, then falls back to environment variables. Located in [agent_reach/config.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py#L75-L84).

Method 1: Using Config Keys (Persistent)

The most permanent way to force a backend is by setting a <channel>_backend key in your Agent Reach configuration file. This key moves the named backend to the front of the candidate list for that specific channel.

Create or edit ~/.agent-reach/config.yaml:

# ~/.agent-reach/config.yaml

youtube_backend: yt-dlp          # Force YouTube to use yt-dlp

twitter_backend: twitter-cli     # Force Twitter to use twitter-cli

reddit_backend: praw             # Force Reddit to use PRAW

After saving, any subsequent agent-reach command will probe your specified backend first before attempting alternatives.

Method 2: Using Environment Variables (Temporary)

For one-off commands, CI pipelines, or testing different backends without modifying config files, use the uppercase environment variable format <CHANNEL>_BACKEND.

# Force YouTube to use the Invidious API backend for this session only

export YOUTUBE_BACKEND=invidious_api
agent-reach search "machine learning tutorials"

# Or use a single command

TWITTER_BACKEND=twscrape agent-reach post "Hello World"

According to the [agent_reach/config.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py#L75-L84) source, Config.get() checks the YAML file first, then falls back to os.getenv. However, because the environment variable check occurs within the same retrieval method, setting an environment variable effectively overrides the config file value for that process.

Programmatic Configuration

You can also force backends programmatically using the Python API:

from agent_reach.config import Config
from agent_reach.channels.youtube import YouTubeChannel

# Method A: Persist to config file

cfg = Config()
cfg.set("youtube_backend", "yt-dlp")  # Saves to ~/.agent-reach/config.yaml

# Method B: Set environment variable for current process

import os
os.environ["YOUTUBE_BACKEND"] = "yt-dlp"

# Initialize and check the channel

yt = YouTubeChannel()
yt.check(config=cfg)      # Probes yt-dlp first due to override

print(yt.active_backend)  # Output: "yt-dlp" (if probe succeeds)

When check() executes, it calls ordered_backends(config) (passing the Config instance). The first backend in the reordered list that returns a successful probe becomes self.active_backend.

Configuration Precedence Rules

When both a config key and environment variable exist for the same channel, the environment variable takes precedence. This occurs because Config.get() evaluates the environment fallback after checking the YAML structure, but the calling context (your shell or script) typically loads environment variables into memory before the Python process starts.

Priority order (highest to lowest):

1. Environment variable (<CHANNEL>_BACKEND) – Temporary, process-specific
2. Config key (<channel>_backend) – Persistent, user-specific
3. Default order – As defined in the channel's backends list

Summary

• Config keys use the format <channel>_backend in ~/.agent-reach/config.yaml for permanent backend preferences.
• Environment variables use the uppercase format <CHANNEL>_BACKEND for temporary overrides ideal for CI/CD or testing.
• The logic is implemented in agent_reach/config.py (Config.get()) and agent_reach/channels/base.py (ordered_backends()).
• Environment variables take precedence over config file settings when both are present.
• The first backend that successfully probes in the reordered list becomes the active backend for that channel instance.

Frequently Asked Questions

What is the naming convention for backend environment variables?

Environment variables use uppercase with underscore separators: <CHANNEL>_BACKEND. For example, use YOUTUBE_BACKEND for YouTube, TWITTER_BACKEND for Twitter, or REDDIT_BACKEND for Reddit. This contrasts with config keys, which use lowercase: youtube_backend, twitter_backend.

Does the environment variable override the config file setting?

Yes. If both a <channel>_backend key exists in ~/.agent-reach/config.yaml and a <CHANNEL>_BACKEND environment variable is set, the environment variable wins. The Config.get() method checks the YAML file first but falls back to os.getenv, and the environment value supersedes the file value in the application logic.

Where is the Agent Reach config file located?

The default configuration file is located at ~/.agent-reach/config.yaml in your home directory. You can create this file manually if it does not exist. The Config class in agent_reach/config.py manages read and write operations to this location.

How do I verify which backend is currently active?

After initializing a channel, check the active_backend attribute. Following a successful check() call, this property contains the string identifier of the working backend. If the forced backend fails to probe, Agent Reach falls back to the next available backend in the ordered list, so always verify channel.active_backend matches your intended override.

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