# Agent Reach Cookie Security Model: How to Handle Private Accounts > Understand the Agent Reach cookie security model. Learn how to handle private accounts safely with manual CLI entry for enhanced session protection. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: internals - Published: 2026-06-07 --- **Agent Reach treats browser cookies as the sole authentication mechanism for API-less platforms, storing them only in a local YAML configuration file and recommending manual CLI entry for private accounts to avoid leaking sessions from shared machines.** Agent Reach is an open-source automation framework that relies on cookie-based authentication for platforms lacking clean token APIs, such as Twitter, XiaoHongShu, Xueqiu, and BiliBili. Because session cookies grant full account access, the Agent Reach cookie security model is designed to keep credentials local, validated, and isolated. For users operating sensitive or isolated profiles—referred to in the project as "private accounts"—the source code explicitly recommends a manual configuration workflow that bypasses automated browser extraction. ## How Agent Reach Extracts and Stores Cookies ### Automated Extraction via Browser Libraries In [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), the library auto-extracts cookies from local browsers by wrapping libraries such as `rookiepy` or `browser-cookie3`. The extraction routine iterates over supported platforms and builds a per-platform cookie map. Once collected, the raw cookie string is persisted through `config.set("_cookie", cookie_str)`, making each platform's credentials available to its respective channel. The CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) orchestrates this flow through functions like `configure_from_browser` and guards such as `needs_cookies`. ### Local YAML Configuration Storage Extracted cookies are stored exclusively in the local `Agent-Reach` configuration file. No cookie data is written into the repository or transmitted to external services. Before persisting, the code validates the presence of required authentication tokens. For example, the Xueqiu channel expects the `xq_a_token` cookie; if it is absent, the extraction logic skips persistence and warns the user. This guard appears in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) near the storage routine. ## Cookie Validation and Session Guards ### The `_cookies_initialized` Flag Each channel that depends on cookies tracks an internal `_cookies_initialized` boolean flag. During startup, the channel's `_ensure_cookies()` method injects the stored cookie string into the session headers. After the first successful injection, the flag flips to `True`. The test suite in [`tests/test_channels.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channels.py) verifies this behavior, ensuring that channels do not accidentally reuse incomplete or stale cookie sets once a session has been primed. ### Required Token Checks Beyond initialization, individual platforms enforce required-token checks. The Xueqiu extractor explicitly looks for `xq_a_token` before calling `config.set`, and the CLI interface in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) emits a warning when a required cookie cannot be located. These checks prevent anonymous or incomplete cookie strings from being mistaken for valid credentials. ## Private Account Recommendations ### Manual CLI Entry for Isolated Profiles Because automated extraction pulls every matching cookie from the default browser profile, it can inadvertently capture sessions belonging to other users on the same machine. For private accounts, the recommended workflow is to bypass auto-extraction and supply the cookie string manually through the CLI. This eliminates the risk of cross-user leakage and guarantees that only the intended session is loaded. Input parsing is rigorously tested in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py), where the `_parse_twitter_cookie_input` helper verifies that both full header strings and individual token pairs are accepted correctly. You can configure a private Twitter account directly: ```bash python -m agent_reach.cli configure twitter-cookies \ "auth_token=YOUR_PRIVATE_TOKEN; ct0=YOUR_PRIVATE_CT0" ``` ### Per-Platform Config Isolation Agent Reach isolates credentials by using distinct configuration keys for each platform, such as `twitter_cookie`, `xhs_cookie`, and `xueqiu_cookie`. This separation prevents token overlap between channels. When managing multiple identities, you should maintain separate config entries for each profile rather than overwriting a single global cookie value. The `doctor` command can verify which keys are populated without exposing their values: ```bash python -m agent_reach.cli doctor ``` ## Auto-Extract vs. Manual Configuration For personal accounts on a trusted single-user machine, **automated extraction** offers a fast setup path. The `install` command triggers the browser extraction flow handled by `configure_from_browser` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py): ```bash python -m agent_reach.cli install --env=auto ``` However, the extraction routine in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) has no knowledge of account boundaries inside the browser. **Manual configuration** is the only method endorsed by the project's security model for private accounts. It bypasses browser scanning and writes the exact cookie string you provide via `config.set("_cookie", cookie_str)`. ## Summary - **Agent Reach uses cookies as the primary authentication mechanism** for platforms like Twitter, XiaoHongShu, Xueqiu, and BiliBili. - **Cookies are stored only in a local YAML config** via `config.set()` inside [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py); they are never committed or transmitted externally. - **Channels guard against stale reuse** with an `_cookies_initialized` flag that `_ensure_cookies()` sets after the first successful injection. - **Private accounts should use manual CLI entry** (`configure -cookies`) rather than browser auto-extraction to avoid leaking other users' sessions. - **Per-platform keys** (`twitter_cookie`, `xhs_cookie`, etc.) keep credentials isolated across channels. ## Frequently Asked Questions ### What is the Agent Reach cookie security model? The Agent Reach cookie security model treats browser session cookies as the sole authentication tokens for platforms without official APIs. Cookies are extracted via [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), validated for required tokens like `xq_a_token`, stored only in a local YAML configuration file, and guarded by per-channel `_cookies_initialized` flags to prevent stale reuse. ### Why should private accounts avoid auto-extraction? Auto-extraction scans the machine's default browser profiles and pulls all matching cookies indiscriminately. On a shared or multi-profile computer, this can capture another user's session. For private accounts, the project recommends manual entry via `python -m agent_reach.cli configure` so that only the intended cookie string is saved under the isolated per-platform config key. ### How does Agent Reach prevent stale cookie reuse? Each cookie-dependent channel maintains an `_cookies_initialized` flag that starts as `False`. The `_ensure_cookies()` method injects the stored cookie string and sets the flag to `True`. Tests in [`tests/test_channels.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channels.py) confirm that this flag prevents repeated or partial re-injection, which could otherwise overwrite headers with stale data. ### Where are Agent Reach cookies physically stored? Agent Reach persists cookies exclusively in the local user configuration file through `config.set("_cookie", cookie_str)`. According to the source code in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) and the CLI tooling in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), no cookie data is written to the repository directory or sent to remote services.