How to Configure YouTube Cookies for Age-Restricted Video Access in Agent Reach

Agent Reach uses yt-dlp to bypass age restrictions by reading browser cookies configured via the youtube-cookies CLI command, storing the origin in ~/.agent-reach/config.yaml for automatic authentication during video retrieval.

Agent Reach is an open-source tool that processes YouTube videos through yt-dlp. When encountering age-restricted or member-only content, the application must present valid authentication credentials from a logged-in browser session. This guide explains how to configure YouTube cookies to unlock restricted content access.

Why YouTube Cookies Are Required for Age-Restricted Content

YouTube restricts certain videos based on age or channel membership status. When Agent Reach requests these videos, yt-dlp acts as the download backend. Without authentication cookies, yt-dlp encounters access barriers and fails to retrieve the video or its subtitles.

By supplying browser cookies through the --cookies-from-browser flag, yt-dlp presents the same session tokens a logged-in user would provide, allowing Agent Reach to process age-restricted and member-only videos seamlessly.

Configuring Cookies via the CLI

Agent Reach provides a dedicated configuration command to set the cookie source. The CLI accepts a youtube-cookies argument that stores the browser profile or cookie file path in the global configuration.

Set the cookie source using a supported browser name:

agent-reach configure youtube-cookies chrome

Or specify a custom browser profile directory:

agent-reach configure youtube-cookies /home/user/.config/google-chrome/Default

Verify the configuration was saved correctly:

agent-reach config show | grep youtube_cookies_from

This outputs the stored value (e.g., youtube_cookies_from: chrome), confirming the configuration persists in the YAML config file.

How the Configuration Works Internally

The cookie authentication flow spans three core components, each handling a specific phase of the configuration and execution pipeline.

CLI Configuration Handling

In agent_reach/cli.py (lines 1092-1096), the configure sub-command parses the youtube-cookies argument and writes the value to the configuration store:

config.set("youtube_cookies_from", value)

This persists the browser identifier or path to ~/.agent-reach/config.yaml, making it available for subsequent video processing requests.

YouTube Channel Implementation

The agent_reach/channels/youtube.py module defines the YouTubeChannel class, which orchestrates video retrieval. When processing a URL, the channel verifies that yt-dlp is installed and that a JavaScript runtime is present through the YouTubeChannel.check method.

During the YouTubeChannel.transcribe call, the channel reads the youtube_cookies_from configuration entry and passes this information to the transcription backend, ensuring yt-dlp receives the authentication context before downloading restricted content.

Command Construction

The agent_reach/utils/paths.py file contains the render_ytdlp_fix_command() function, which constructs the final yt-dlp execution string. When the youtube_cookies_from key exists in the configuration, this function appends the --cookies-from-browser flag with the configured value:

--cookies-from-browser <value>

This flag instructs yt-dlp to read the SQLite cookie database from the specified browser profile, authenticating the request exactly as a real browser would.

Step-by-Step Usage Example

Follow this workflow to access age-restricted content after configuring your cookies:

1. Configure the cookie source for your default browser:

   agent-reach configure youtube-cookies firefox

2. Verify the configuration entry exists:

   agent-reach config show

3. Process a restricted video by URL:

   agent-reach read https://www.youtube.com/watch?v=RESTRICTED_ID

4. Extract subtitles only from restricted content:

   agent-reach read --transcribe https://youtu.be/RESTRICTED_ID

When executing these commands, Agent Reach automatically invokes yt-dlp with the --cookies-from-browser flag, supplying the necessary authentication tokens to bypass age verification gates.

Summary

• yt-dlp integration handles the actual cookie authentication and video download.
• Configuration storage occurs in ~/.agent-reach/config.yaml via the youtube_cookies_from key.
• CLI command agent-reach configure youtube-cookies <value> sets the browser profile or path.
• Internal implementation spans agent_reach/cli.py, agent_reach/channels/youtube.py, and agent_reach/utils/paths.py.
• Authentication bypass works by passing --cookies-from-browser to yt-dlp during the YouTubeChannel.check → YouTubeChannel.transcribe execution flow.

Frequently Asked Questions

What browsers are supported for cookie extraction?

Agent Reach supports any browser that yt-dlp can read cookies from, including Chrome, Edge, Firefox, Safari, and Chromium derivatives. The configuration value can be the browser name (e.g., chrome) or an absolute path to the profile directory containing the cookies SQLite database.

Can I use a custom cookie file instead of a browser profile?

Yes. While the documentation emphasizes browser profile names like chrome or firefox, you can provide an absolute path to a custom cookie storage location. For example: agent-reach configure youtube-cookies /path/to/custom/cookies.txt. The render_ytdlp_fix_command() function in agent_reach/utils/paths.py passes this value directly to yt-dlp's --cookies-from-browser or --cookies parameter depending on the format.

Why does Agent Reach need my browser cookies?

Age-restricted and member-only videos require authentication that proves you are logged into a YouTube account meeting the viewing criteria. Agent Reach does not handle login flows directly; instead, it leverages yt-dlp's ability to read existing browser sessions. By accessing your browser's cookie store, yt-dlp presents valid session tokens to YouTube's servers, satisfying access control checks without requiring manual credential entry.

Where is the cookie configuration stored?

The configuration persists in the global YAML config file at ~/.agent-reach/config.yaml under the key youtube_cookies_from. This value is written by the CLI handler in agent_reach/cli.py and read by the YouTube channel implementation in agent_reach/channels/youtube.py during video processing operations.

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