Why Agent-Reach Requires Dedicated Accounts Instead of Main Credentials for Social Platforms

Agent-Reach requires dedicated accounts instead of main credentials because upstream CLI tools need personal session cookies to access protected content on social platforms, while the core library remains credential-agnostic to ensure security and privacy.

Agent-Reach functions as a capability layer that routes AI agent requests to command-line tools for interacting with online services. While public, read-only content like generic webpages or RSS feeds needs no authentication, social platforms enforce strict access controls that make dedicated accounts necessary for full functionality.

Platform-Level Authentication Barriers

Major social networks block anonymous API calls and only expose full content to logged-in browser sessions. Platforms like Twitter/X, Reddit, Facebook, Instagram, and XiaoHongShu require an authenticated session to view posts, comments, or direct messages.

In agent_reach/channels/twitter.py, the TwitterChannel._check_twitter_cli method implements a two-stage probe that detects when the upstream tool reports a not_authenticated flag. When this occurs, the channel emits a warning status and instructs the user to provide credentials rather than attempting to proceed with anonymous access. This design prevents the agent from hitting authentication walls mid-operation.

Cookie-Based Authentication vs. API Keys

Unlike traditional API integrations that rely on embedded keys, Agent-Reach leverages cookie-based authentication through tools like OpenCLI, which reuse the Chrome login session stored on the local machine. This approach avoids exposing API keys in the codebase and respects the platform's preferred authentication flow.

According to the docs/README_en.md – Supported Platforms section, these platforms are explicitly marked as "Cookie" required. When the agent requests to configure a platform (e.g., "帮我配 Twitter"), the system triggers a guided login flow that stores session cookies locally rather than transmitting credentials to remote servers.

Rate Limits and Cost Avoidance

Public APIs for platforms like Twitter often require expensive paid plans with strict rate limits. By utilizing dedicated accounts through free CLI wrappers such as twitter-cli, rdt-cli, or bird, Agent-Reach bypasses official API quotas while respecting platform usage policies. The personal session acts as the authentication mechanism, eliminating the need for shared API keys or enterprise contracts that would otherwise gate access.

Privacy and Session Isolation

Dedicated accounts ensure that one agent’s actions never leak into another agent’s workspace. Each platform channel stores cookie files locally on the user's machine, and the docs/README_en.md – Privacy section explicitly states that cookies remain on the user’s machine and are never uploaded to the repository or remote services. This isolation protects personal data such as direct messages and protected posts, keeping them under the end-user's exclusive control.

How Agent-Reach Detects Missing Credentials

The system implements a health-check pattern that verifies authentication status before attempting operations. The TwitterChannel class (and analogous implementations in agent_reach/channels/reddit.py) probes the underlying CLI tool to determine if a valid session exists.

from agent_reach.channels.twitter import TwitterChannel

# The `check` method runs the two-stage probe described above.

status, msg = TwitterChannel().check()
print(status)   # → "ok", "warn", or "error"

print(msg)      # Detailed instructions for missing login

When agent_reach/doctor.py runs health checks across all channels, it reports whether each backend is "ok", "warn", or "error", providing specific remediation steps for platforms lacking dedicated accounts.

Configuring Dedicated Accounts

To establish a dedicated account, users install the appropriate CLI tool and execute the platform-specific login command. For example, configuring Reddit requires:

# Install the upstream CLI

pipx install rdt-cli

# OpenCLI auto-extracts Chrome cookies if logged in,

# otherwise run explicit login:

rdt login          # Opens browser; stores session after acceptance

The agent_reach/cli.py entry point provides guided configuration through commands like:

# Triggers the configuration flow for Twitter

python -m agent_reach.cli config --platform twitter

# Verifies all backends are properly authenticated

python -m agent_reach.cli doctor

Summary

• Agent-Reach routes requests through upstream CLI tools that require personal sessions, not shared credentials.
• Social platforms block anonymous access; the system detects not_authenticated states in agent_reach/channels/twitter.py and similar channel files.
• Cookie-based authentication reuses local browser sessions, avoiding API key exposure and costly rate limits.
• Credentials remain isolated on the local machine, ensuring privacy and preventing cross-agent data leakage.
• The doctor.py health check and CLI configuration flows guide users through installing tools and running login commands like rdt login or twitter login.

Frequently Asked Questions

Why can't Agent-Reach use a single shared API key for all users?

Shared API keys violate the terms of service for most social platforms and would hit rate limits immediately. The architecture in Panniantong/Agent-Reach deliberately avoids embedding credentials, instead requiring each user to provide their own dedicated account session. This ensures compliance with platform policies while preventing unauthorized access to private content.

How does Agent-Reach store my login credentials?

The system does not store passwords or API keys. According to the privacy documentation in docs/README_en.md, only session cookies are saved locally on your machine. These cookie files are never uploaded to remote repositories or cloud services, ensuring that your personal data remains under your exclusive control.

What happens if I don't configure a dedicated account for a platform?

If a required CLI tool is installed but lacks authentication, the channel's check method (such as TwitterChannel._check_twitter_cli) returns a "warn" status with specific instructions. The agent cannot access protected content on that platform until you complete the login flow (e.g., running twitter login or exporting Chrome cookies), though public read-only sources remain accessible.

Which platforms require dedicated accounts versus public access?

Public, read-only services like generic webpages, YouTube videos, and RSS feeds require no authentication. However, social platforms including Twitter/X, Reddit, Facebook, Instagram, and XiaoHongShu require dedicated accounts because they block anonymous API calls and only expose full content to logged-in sessions, as documented in the Supported Platforms section of docs/README_en.md.

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