# How to Add a Custom Backend Override for a Channel in Agent-Reach > Learn to add a custom backend override for AgentReach channels. Set the channel_backend key in config.yaml or CHANNEL_BACKEND environment variable to reorder candidates without removing fallbacks. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-06-28 --- **You can override the default backend for any Agent-Reach channel by setting the `_backend` key in `~/.agent-reach/config.yaml` or the `_BACKEND` environment variable, which reorders the candidate list without removing fallback options.** Agent-Reach is a modular platform router that delegates read and search operations to external CLI tools called *backends*. Each channel (such as YouTube, Twitter, or Reddit) maintains an ordered list of compatible backends. To customize which backend is tried first for a specific channel, you can add a custom backend override for a channel in Agent-Reach through configuration files, environment variables, or the programmatic API. ## Understanding Channel Backends in Agent-Reach In the Agent-Reach architecture, every channel inherits from the base class defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). Each channel implementation specifies a list attribute called `backends` that contains the names of compatible CLI tools in order of preference. When a channel initializes or runs diagnostics, it calls the `check()` method, which iterates through the candidate backends and selects the first usable tool. This selected backend is stored in the instance attribute `self.active_backend` and handles all subsequent operations for that channel. ## How Backend Override Works The core logic for adding a custom backend override resides in the `ordered_backends()` method of [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45-59). This method accepts an optional `config` parameter and returns a reordered list of candidate backends: ```python # agent_reach/channels/base.py def ordered_backends(self, config=None) -> List[str]: """Candidate backends in probe order, honoring the user override.""" candidates = list(self.backends) override = config.get(f"{self.name}_backend") if config else None if override: for i, b in enumerate(candidates): if b == override or b.startswith(override): candidates.insert(0, candidates.pop(i)) break return candidates ``` When you add a custom backend override, the method searches for a match (exact or prefix) in the candidate list. If found, it moves that backend to the front of the list (index 0) but preserves all other candidates as fallbacks. This ensures that if your specified backend is unavailable, the channel can still fall back to the default options rather than failing entirely. ## Methods to Configure a Custom Backend Override Agent-Reach provides three mechanisms to inject your override: YAML configuration files, environment variables, and direct programmatic access. ### Using the YAML Configuration File The most persistent method is to edit the user configuration file at `~/.agent-reach/config.yaml`. Add a key using the format `_backend` followed by the desired tool name: ```yaml # ~/.agent-reach/config.yaml youtube_backend: yt-dlp # Prefer yt-dlp over the built-in extractor twitter_backend: bird # Use the 'bird' CLI instead of the default ``` After saving the file, any new `AgentReach` instance will load this configuration and apply the override when `ordered_backends()` is called during channel initialization. ### Using Environment Variables For temporary or session-specific overrides, set an environment variable using the uppercase format `_BACKEND`. According to [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 70-78), the `Config.get()` method automatically reads these variables and passes them to the channel configuration: ```bash export TWITTER_BACKEND=bird python -m agent_reach.cli read https://twitter.com/example/status/12345 ``` This approach is ideal for CI/CD pipelines or one-off commands where you do not want to modify the persistent config file. ### Programmatic Configuration You can also add a custom backend override dynamically within a Python script using the `Config` class: ```python from agent_reach.config import Config from agent_reach.core import AgentReach cfg = Config() cfg.set("twitter_backend", "bird") # Persists the override in the config file ar = AgentReach(cfg) result = ar.read("https://twitter.com/example/status/12345") ``` The `Config.set()` method writes the value to the configuration store, making it available for subsequent calls to `ordered_backends()` without manually editing YAML files. ## Verifying Your Backend Override To confirm that your custom backend override is active, inspect the `active_backend` attribute after running the channel's diagnostic check: ```python from agent_reach.config import Config from agent_reach.core import AgentReach cfg = Config() ar = AgentReach(cfg) status, msg = ar.channels["twitter"].check(cfg.data) print(f"Active backend: {ar.channels['twitter'].active_backend}") # e.g., bird ``` This verification pattern is tested in [`tests/test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channel_contracts.py), which validates that the override logic correctly reorders the backend priority list while maintaining fallback candidates. ## Summary - **Agent-Reach channels** use an ordered `backends` list defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) to select external CLI tools. - The **`ordered_backends()`** method (lines 45-59) implements the override logic by moving your specified backend to the front of the candidate list. - You can add a **custom backend override** via the `~/.agent-reach/config.yaml` file using the `_backend` key, or temporarily via the `_BACKEND` environment variable. - The **`Config`** class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 70-78) handles the merging of file-based and environment-based configuration. - Overrides are **reordering operations**, not replacements, ensuring fallback backends remain available if the specified tool is unavailable. ## Frequently Asked Questions ### What happens if I specify a backend that isn't installed? If the backend you specify in your custom override is not found or is unusable, the channel falls back to the next available backend in the `ordered_backends()` list. The logic in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) only reorders the candidates; it does not remove them, so the channel will attempt the default backends if your specified tool fails the `check()` diagnostic. ### Can I override multiple channels at once? Yes. You can define multiple `_backend` entries in the same `~/.agent-reach/config.yaml` file, such as `youtube_backend`, `twitter_backend`, and `reddit_backend` simultaneously. Each key is independent and only affects the channel matching that specific name. ### Is the environment variable override permanent? No. Environment variables provide a temporary override for the current session only. Once you close the terminal or unset the variable (e.g., `unset TWITTER_BACKEND`), Agent-Reach reverts to the priorities defined in the YAML config file or the channel's default `backends` list. ### Does the backend name need to match exactly? The `ordered_backends()` method uses either an exact match or a prefix match (`b.startswith(override)`). This means you can specify a short prefix if it uniquely identifies the backend, though using the full tool name (e.g., `"yt-dlp"`) is recommended for clarity and to avoid ambiguity.