How to Configure YouTube Cookies in Agent Reach for Age-Restricted or Member-Only Videos

Run agent-reach configure youtube-cookies <browser-or-file> to store a cookie source in ~/.agent-reach/config.yaml, which Agent Reach automatically forwards to yt-dlp so the agent can fetch metadata and subtitles from age-restricted or member-only videos.

The open-source Panniantong/Agent-Reach repository relies on yt-dlp to handle YouTube content. Because age-restricted and members-only videos require an authenticated YouTube session, you must configure YouTube cookies in Agent Reach before the agent can process these URLs.

Why yt-dlp Requires Cookies for Restricted Videos

Agent Reach delegates all YouTube fetching to yt-dlp. When a video is age-restricted or locked behind a membership gate, yt-dlp must present valid session cookies to prove the account is logged in and authorized. Without cookies, yt-dlp hits the age-gate or paywall and cannot return metadata or subtitles.

How to Configure YouTube Cookies in Agent Reach

Step 1: Choose a Cookie Source

yt-dlp accepts authentication via two methods:

• Browser profile – Pass a supported browser name such as chrome, firefox, edge, brave, or opera. yt-dlp reads cookies directly from that browser's profile using --cookies-from-browser.
• Cookie file – Pass the full path to a cookies.txt file exported from a browser extension such as Cookie-Editor. yt-dlp loads this via --cookies.

Step 2: Run the Configuration Command

Use the built-in CLI command. Under the hood, agent_reach/cli.py calls config.set("youtube_cookies_from", value) around line 1108 and persists the setting to ~/.agent-reach/config.yaml.

Configure from a browser:

agent-reach configure youtube-cookies chrome

Configure from a file:

agent-reach configure youtube-cookies ~/my_youtube_cookies.txt

The resulting configuration looks like this:

youtube_cookies_from: chrome

Or, for a file path:

youtube_cookies_from: /home/youruser/my_youtube_cookies.txt

The read and write logic lives in agent_reach/config.py inside the set() and get() methods (lines 79–84).

Step 3: Verify the Setup

Run the optional diagnostic command:

agent-reach doctor

The check() method in agent_reach/channels/youtube.py (lines 23–46) validates that yt-dlp is present and that a JavaScript runtime is configured. A successful run confirms that the YouTube cookie source is active and ready for restricted content.

JavaScript Runtime Requirement

yt-dlp needs Node.js or Deno to execute JavaScript on modern YouTube pages. If a runtime is missing, the check() method in agent_reach/channels/youtube.py reports the error, and the CLI suggests the helper command generated by render_ytdlp_fix_command() in agent_reach/utils/paths.py (lines 29–45). This helper typically adds --js-runtimes node to your yt-dlp configuration. Run agent-reach install if the runtime is still missing.

How Agent Reach Uses the Cookie Setting

When you submit a YouTube command such as:

agent-reach read "https://youtube.com/watch?v=XYZ"

Agent Reach reads youtube_cookies_from from agent_reach/config.py and injects the appropriate flag into the internal yt-dlp call. For browser sources, the generated command resembles:

yt-dlp --dump-json --cookies-from-browser chrome "https://youtube.com/watch?v=XYZ"

For file sources, it becomes:

yt-dlp --dump-json --cookies /home/youruser/my_youtube_cookies.txt "https://youtube.com/watch?v=XYZ"

Your session credentials remain local and are never uploaded to any server.

Key Source Files

• agent_reach/cli.py – Implements the configure sub-command and writes the cookie source via config.set("youtube_cookies_from", value).
• agent_reach/config.py – Persists user settings to ~/.agent-reach/config.yaml through the set() and get() methods (lines 79–84).
• agent_reach/channels/youtube.py – The check() method (lines 23–46) ensures yt-dlp and a JS runtime are available before processing restricted videos.
• agent_reach/utils/paths.py – render_ytdlp_fix_command() (lines 29–45) generates repair instructions when yt-dlp cannot locate Node.js or Deno.
• agent_reach/skill/references/video.md – Internal documentation (line 69) recommending --cookies-from-browser for restricted and member-only videos.

Summary

• Run agent-reach configure youtube-cookies <source> to configure YouTube cookies in Agent Reach.
• Supported sources include browser names (chrome, firefox, edge, brave, opera) or a local file path.
• The value is stored in ~/.agent-reach/config.yaml via agent_reach/config.py.
• Use agent-reach doctor to invoke the YouTubeChannel.check() routine and confirm dependencies.
• A Node.js or Deno runtime is required; render_ytdlp_fix_command() in agent_reach/utils/paths.py provides repair hints if it is missing.
• Cookies are only used locally and are never uploaded.

Frequently Asked Questions

What cookie sources does Agent Reach support?

Agent Reach supports any browser profile that yt-dlp can read: chrome, firefox, edge, brave, and opera. You can also supply the absolute path to a cookies.txt file exported from a browser extension such as Cookie-Editor.

Why does agent-reach doctor warn about a missing JavaScript runtime?

yt-dlp needs Node.js or Deno to evaluate JavaScript on YouTube’s dynamic pages. The check() method in agent_reach/channels/youtube.py (lines 23–46) detects missing runtimes, and render_ytdlp_fix_command() in agent_reach/utils/paths.py (lines 29–45) generates the command to fix it. If the warning persists, run agent-reach install to resolve dependencies.

Is my cookie data uploaded to any remote server?

No. The cookies are stored locally in ~/.agent-reach/config.yaml and passed directly to the local yt-dlp process via --cookies-from-browser or --cookies. They never leave your machine.

Can I change my cookie source after initial configuration?

Yes. Simply run agent-reach configure youtube-cookies <new-source> again. The configure handler in agent_reach/cli.py calls config.set("youtube_cookies_from", value), which overwrites the previous entry in your configuration file immediately.

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