AdsPower — Master Knowledge Base for Hermes-Driven Reddit Marketing

Unified reference combining the three analysis sections (01 Local API, 02 CLI/Skill, 03 MCP/RPA) into a single operator handbook. Source files: 01-local-api.md, 02-cli-skill.md, 03-mcp-rpa.md in this directory. Generated by synthesis task t_04ec6af5.

1. Executive Summary

AdsPower is an anti-detect browser that runs many isolated browser profiles, each with its own fingerprint (canvas, WebGL, UA, timezone, WebRTC) and network identity (proxy). For Reddit marketing at scale, each AdsPower profile = one Reddit account, isolated from the others by fingerprint + proxy + cookie jar.

There are four integration layers, each with a distinct role. Using the wrong layer breaks the workflow:

Layer	What it does	Who drives it	Used for Reddit?
Local REST API	Profile lifecycle, groups, tags, proxies, kernels — HTTP endpoints on `:50325`	Any HTTP client	Foundation — all programmatic mgmt
`ads` CLI / Hermes skill	Shell wrapper over the Local API; `ads <command> '{json}'`	Hermes agent (terminal)	Profile farm CRUD — primary interface for agents
MCP Server	Playwright-backed browser automation exposed as MCP tools (navigate, click, fill, screenshot)	Hermes agent (MCP client)	In-page Reddit actions (upvote, comment, post) — the engagement engine
RPA	Visual drag-and-drop process builder inside AdsPower GUI	Human operator in AdsPower UI	Bulk fixed-workflow runs across up to 100 profiles — not Hermes-callable

Rule of thumb: the CLI manages profiles; the MCP server drives them. The CLI can launch a browser but cannot click inside it. RPA is a human bulk tool — Hermes can generate process definitions for a human to import, but cannot trigger RPA runs programmatically.

Architecture for Rahul’s setup (Hostinger Linux VPS + Windows AdsPower host):

┌──────────────────────────────────────────────────────────────────────────┐
│  Hermes Agent (Linux VPS, 89.117.36.36)                                  │
│                                                                          │
│  ┌────────────────┐    ┌──────────────────────────────────────────────┐ │
│  │ ads CLI        │    │ MCP client                                   │ │
│  │ (skill:        │    │   tools: mcp_adspower_<navigate|click|...>   │ │
│  │  adspower-     │    │                                              │ │
│  │  browser)      │    │   stdio JSON-RPC                             │ │
│  └──────┬─────────┘    └──────────────┬───────────────────────────────┘ │
│         │ HTTP                        │ spawn (npx -y local-api-mcp-    │
│         │ :50325                      │  typescript)                    │
└─────────┼─────────────────────────────┼──────────────────────────────────┘
          │                             │ HTTP :50325
          │                             ▼
          │             ┌─────────────────────────────────┐
          │             │ local-api-mcp-typescript        │
          │             │ (Playwright + TS, on VPS)       │
          │             └────────────┬────────────────────┘
          │                          │ WebSocket (ws.puppeteer)
          ▼                          ▼
   ┌─────────────────────────────────────────────────────┐
   │  AdsPower (Windows host — Rahul's PC or Windows VPS)│
   │  Local API on 0.0.0.0:50325, Bearer token           │
   │                                                     │
   │  Profile A (proxy US-1) ──► Reddit account @alpha1  │
   │  Profile B (proxy US-2) ──► Reddit account @alpha2  │
   │  Profile C (proxy DE-1) ──► Reddit account @beta1   │
   │  ...                                                 │
   └─────────────────────────────────────────────────────┘

Why split across two machines: AdsPower is a desktop app (Windows/macOS) and cannot run on the Hostinger Linux VPS. The MCP server (Node.js) runs on the VPS and points at the remote AdsPower Local API. The ads CLI on the VPS hits the same remote endpoint via --port/--api-key flags or env vars.

2. Authentication & Connection

Item	Value
Auth method	Bearer Token (API Key)
Token source	AdsPower client → Automation → API → Generate
Default base URL	`http://localhost:50325` (same machine) or `http://<windows-host>:50325` (remote)
CLI auth	`ads start -k <KEY>` or `export ADS_API_KEY=<KEY>`
MCP auth	env var in Hermes config (verify exact name post-install)
Headless mode	`adspower_global --headless=true --api-key=<KEY> --api-port=50325` (Linux)
API key reset	Stop service → reset → restart. Invalidates old key immediately.
API verification	Must be disabled in AdsPower for MCP/programmatic calls (trusted profiles only)

When API key is required: CLI/headless mode (always), security-verification-enabled mode (always), GUI mode without verification (optional but recommended).

3. Rate Limits

Profile count in account	Standard endpoint rate
0–200	2 req/sec
200–5000	5 req/sec
5000+	10 req/sec

Fixed 1 req/sec endpoints (always, regardless of profile count):

GET /api/v1/user/list
POST /api/v2/browser-profile/list
GET /api/v1/group/list
POST /api/v2/browser-profile/cookies
POST /api/v2/browser-profile/download-kernel

Reddit workflow implication: with <200 profiles you can open/close 2 profiles/sec — a 50-profile campaign opens in ~25s. But profile list polling is capped at 1/sec; use active/active-local endpoints (standard rate) for status checks, not the list endpoint.

4. Complete API/CLI Reference (Condensed)

Full detail in 01-local-api.md (REST) and 02-cli-skill.md (CLI). Below is the operator-facing cheat sheet.

4.1 Connection & Runtime

CLI	Endpoint	Purpose
`ads status`	—	Local API runtime status
`ads check-status`	`GET /status`	Ping API availability
`ads start [-k KEY]`	—	Start runtime
`ads stop` / `ads restart`	—	Stop / restart runtime

4.2 Profile Lifecycle (open/close/status)

CLI	Endpoint	Key params
`ads open-browser <id\|json>`	`POST /api/v2/browser-profile/start`	`profile_id` or `profile_no`; `headless`, `launch_args`, `last_opened_tabs`, `proxy_detection`, `cdp_mask`, `delete_cache`. Returns `ws.puppeteer`, `ws.selenium`, `debug_port` — hand these to MCP/Playwright.
`ads close-browser <id>`	`POST /api/v2/browser-profile/stop`	`profile_id` or `profile_no`
`ads close-all-profiles`	`POST /api/v1/browser/stop-all`	Emergency close
`ads get-browser-active <id>`	`GET /api/v2/browser-profile/active`	Returns `status` (Active/Inactive) + `ws`/`debug_port` when Active
`ads get-cloud-active`	—	Cloud-side status, up to 100 comma-separated IDs
`ads get-opened-browser`	—	List all profiles open on this device

4.3 Profile CRUD

CLI	Endpoint	Required	Notes
`ads create-browser '{json}'`	`POST /api/v2/browser-profile/create`	`group_id`, one of `username`/`password`/`cookie`/`fakey`, `fingerprint_config` (non-empty)	`user_proxy_config` OR `proxyid` for proxy; `proxyid` takes priority. Multi-account via `platform_account[]`.
`ads update-browser '{json}'`	`POST /api/v2/browser-profile/update`	`profile_id`	Same fields as create + `tags_update_type` (`1`=replace, `2`=append)
`ads delete-browser '{json}'`	`POST /api/v2/browser-profile/delete`	`profile_id[]`	—
`ads get-browser-list '{}'`	`POST /api/v2/browser-profile/list`	—	1 req/sec. CLI defaults `page=1, limit=200`. Loop pages by `total_pages`.

4.4 Profile Management

CLI	Purpose
`ads move-browser`	Move profiles to a group (`group_id` + `user_ids[]`)
`ads get-profile-cookies <id>`	Read cookies (1 req/sec)
`ads get-profile-ua <id>`	UA for up to 10 profiles
`ads new-fingerprint <id>`	Regenerate fingerprint for up to 10 profiles
`ads delete-cache-v2 '{json}'`	Clear by type: `local_storage`, `indexeddb`, `extension_cache`, `cookie`, `history`, `image_file`. Profile must be closed.
`ads share-profile`	Share to email/phone (max 200)

4.5 Groups / Tags / Proxies / Kernels / Patch

Domain	CLI commands	Notes
Groups	`create-group`, `update-group`, `get-group-list`	`group_name` (≤30 chars, unique); `get-group-list` is 1 req/sec
Tags	`get-tag-list`, `create-tag`, `update-tag`, `delete-tag`	Colors: darkBlue/blue/purple/red/yellow/orange/green/lightGreen. Max 30 tags/profile.
Proxies	`create-proxy`, `update-proxy`, `get-proxy-list`, `delete-proxy`	`create-proxy` takes a top-level JSON array. Types: http/https/ssh/socks5. Max 500/request.
Kernels	`get-kernel-list`, `download-kernel`	`kernel_type`: Chrome/Firefox; `download-kernel` is 1 req/sec
Patch	`update-patch`	`version_type`: stable (default) / beta

4.6 Inline Config Objects

user_proxy_config (for create/update-browser; ignored if proxyid given):

Field	Required	Values
`proxy_soft`	yes	`brightdata`/`brightauto`/`oxylabsauto`/`ipfoxyauto`/`kookauto`/`ssh`/`other`/`adspowerauto`/`no_proxy`
`proxy_type`	no	`http`/`https`/`socks5`
`proxy_host`/`proxy_port`	no	IP + port
`proxy_user`/`proxy_password`	no	Auth
`proxy_url`	no	IP-change link (mobile proxies)

fingerprint_config (required, non-empty). Reddit-critical fields:

Field	Default	Recommendation for Reddit
`automatic_timezone`	`1` (by IP)	Keep `1` — matches proxy geo
`webrtc`	`disabled`	`proxy` — prevents WebRTC IP leak revealing real IP
`language_switch`	`1` (by IP)	Keep `1` — matches proxy locale
`canvas`/`webgl_image`/`audio`	`1` (noise)	Keep noise on — anti-detect
`screen_resolution`	`none`	`random` for variety
`browser_kernel_config`	—	`{"type":"chrome","version":"ua_auto"}`
`random_ua`	—	Vary OS version per profile

Full field list: /opt/data/skills/adspower-browser/references/fingerprint-config.md.

5. Automation Capabilities — MCP vs RPA

Capability	CLI/Skill	MCP Server	RPA
Create/update/delete profiles	✅	—	—
Open/close browser profiles	✅	—	—
Manage groups/tags/proxies/kernels	✅	—	—
Read cookies/UA/active status	✅	—	—
Navigate to URL inside browser	❌	✅ `navigate`	✅
Click elements / fill inputs	❌	✅ `click-element`/`fill-input`	✅
Screenshot / read page text	❌	✅ `screenshot`/`get-page-visible-text`	✅
Execute JS in page	❌	✅ `evaluate-script`	✅
Connect Playwright via WS	❌	✅ `connect-browser-with-ws`	—
Concurrency	n/a	One profile per AI turn (sequential)	Up to 100 threads
Triggered by Hermes	✅	✅	❌ (GUI-only)
Flexibility	n/a	AI decides at runtime	Fixed sequence upfront

Hybrid recommendation: MCP Server is the primary Hermes-driven layer (adaptive: AI decides what to engage, writes context-aware comments, handles errors). RPA is the volume layer — once a workflow is nailed down, Hermes generates the process definition, a human imports it into RPA, and it runs across 100 profiles concurrently.

6. Profile/Group/Proxy Management Procedures

6.1 Provisioning N Reddit Profiles (CLI)

# 1. Create a group
ads create-group '{"group_name":"reddit-marketing","remark":"GrowReach Reddit personas"}'
# → note group_id
 
# 2. (Optional) Pre-create proxies and reference by proxyid
ads create-proxy '[{"type":"http","host":"us.proxy1.com","port":"8080","proxy_user":"u1","proxy_password":"p1"},
                   {"type":"socks5","host":"us.proxy2.com","port":"1080"}]'
# → note proxy_ids
 
# 3. Create N profiles — one per Reddit account
for i in 1..N; do
  ads create-browser '{
    "name": "reddit-'$i'",
    "group_id": "<gid>",
    "platform": "reddit.com",
    "username": "<reddit_username_'$i'>",
    "password": "<reddit_password_'$i'>",
    "country": "us",
    "proxyid": "<proxy_id_'$i'>",
    "fingerprint_config": {
      "webrtc": "proxy",
      "automatic_timezone": "1",
      "language_switch": "1",
      "canvas": "1", "webgl_image": "1", "audio": "1",
      "screen_resolution": "random",
      "browser_kernel_config": {"type":"chrome","version":"ua_auto"}
    }
  }'
done
 
# 4. Tag by persona
ads create-tag '{"tags":[{"name":"saas-founder","color":"blue"}]}'
ads update-browser '{"profile_id":"<id>","profile_tag_ids":["<tag_id>"],"tags_update_type":"1"}'

6.2 Periodic Maintenance

Task	Command	Cadence
Rotate fingerprint	`ads new-fingerprint <id>` (batch 10)	Weekly
Clear cookies/history	`ads delete-cache-v2 '{"profile_id":["..."],"type":["cookie","history","local_storage"]}'`	Between campaigns or on ban suspicion
Audit profile list	`ads get-browser-list '{"group_id":"<gid>","limit":200}'` (loop pages)	Weekly
Check active status	`ads get-browser-active <id>` (use active, not list — faster)	Per session

6.3 Emergency Stop

ads close-all-profiles   # close everything on this device

7. Reddit Workflow — End-to-End Loop

Prepare: proxies created, group created, N profiles provisioned (§6.1).
For each profile (sequential via MCP, or bulk via RPA):
- ads open-browser <profile_id> → returns ws.puppeteer
- MCP attaches Playwright via the ws endpoint
- navigate to Reddit post URL
- (Login if needed — fill username/password, handle 2FA)
- click-element upvote arrow
- fill-input comment box + comment text (AI-authored)
- click-element submit
- screenshot for proof
- ads close-browser <profile_id>
Human-like pacing: randomized delays between actions (see integration plan §Phase 4).
Log outcome per profile (success/banned/captcha) to task log.

8. Key Risks & Open Questions

Risk	Mitigation	Status
AdsPower desktop-only — can’t run on Linux VPS	Run on Windows host reachable from Hermes VPS; MCP server on VPS points at remote `:50325`	Decision needed: Rahul’s PC vs Windows VPS
MCP env-var names for remote LocalAPI endpoint	Verify after `npx -y local-api-mcp-typescript` install — `hermes mcp test adspower`	Post-install
API verification disabled = security trade-off	Only disable for trusted profiles; keep Bearer token; firewall `:50325` to VPS IP only	Required for MCP
Reddit anti-manipulation	Unique proxy per profile, human-like delays, fingerprint rotation, avoid identical comment text, limit actions/account/day	Operational discipline
AdsPower rate limit (2 req/sec for <200 profiles)	Queue profile opens with 0.6s spacing; never poll `list` at >1/sec	Built into orchestration
RPA has no external API	Use MCP for Hermes-driven work; RPA stays human-triggered for bulk	Accepted
Exact MCP tool surface	Discovered via `hermes mcp test adspower` post-connection	Post-install

9. File Index

File	Contents
`00-master-kb.md`	This file — unified reference
`01-local-api.md`	REST API: 43 endpoints, auth, rate limits, config objects
`02-cli-skill.md`	`ads` CLI: 32 commands, intent mapping, CLI≠automation boundary
`03-mcp-rpa.md`	MCP Server + RPA: architecture, Hermes integration, hybrid recommendation
`04-integration-plan.md`	5-phase actionable integration plan
`05-profile-recommendation.md`	Hermes profile setup for the AdsPower operator

Skill reference files: /opt/data/skills/adspower-browser/references/ (14 files).

Explorer

Master KB