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

> Force a specific backend in Agent Reach using environment variables or config keys. Prioritize your preferred backend for any channel efficiently and easily.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-18

---

**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)](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)](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`:

```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`.

```bash

# 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)](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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (`Config.get()`) and [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.