Give each AI agent a persistent, reusable browser identity.

Before you start

• AliasMode installed on Windows (drive it remotely from macOS/Linux via Remote MCP or the Local API on a reachable host)
• A Playwright or Puppeteer project in your agent stack
• One AliasMode profile per agent, with a named login per site it works on
• Local API reachable at 127.0.0.1:50400 on the host

Step-by-step

1. 1

   Create one profile per agent

   Name profiles after agents, not tasks: agent·researcher, agent·poster. Tasks change weekly; the identity should not. Keep the generated fingerprint seed fixed.

2. 2

   Seed the logins once

   Launch the profile by hand, log into the sites the agent needs, and close it. From now on the agent inherits those sessions on every run.

3. 3

   List profiles from the API

   Have your agent tooling discover profile IDs instead of hardcoding them.

   Step 3

   curl 'http://127.0.0.1:50400/api/v1/user/list'

4. 4

   Start the profile for a run

   Start the browser for the run and read the CDP endpoint from the response.

   Step 4

   const res = await fetch('http://127.0.0.1:50400/api/v1/browser/start?user_id=' + profileId);
   const { data } = await res.json();
   const cdp = data.ws.puppeteer; // chromium.connectOverCDP(cdp)

5. 5

   Connect the agent over CDP

   Connect Playwright or Puppeteer to the running profile. Everything the agent does lands in the same persistent session.

   Step 5

   const browser = await chromium.connectOverCDP(cdp);
   const context = browser.contexts()[0];
   // agent drives page work inside the logged-in profile

6. 6

   Stop the browser cleanly

   End every run by stopping the profile so state syncs and the next run starts from a clean launch, not a zombie browser.

   Step 6

   await browser.close();
   await fetch('http://127.0.0.1:50400/api/v1/browser/stop?user_id=' + profileId);

7. 7

   Assign one agent per profile

   Two agents sharing one profile fight over the same sessions and cookies. One identity per agent keeps runs deterministic and logs attributable.

8. 8

   Handle re-auth gracefully

   When a site invalidates the session, the agent should detect the login page, stop, and alert a human — seeding logins stays a supervised step.

The AliasMode workflow

1. 1

   Profiles as agent identities

   One profile per agent, grouped by project, with tags for the sites each agent may touch.

2. 2

   Local API as the control plane

   Start, stop, and list profiles over HTTP on the loopback — the AdsPower-shaped API your orchestration already expects.

3. 3

   MCP for agent clients

   Claude Code, Codex, OpenClaw, and Hermes drive AliasMode through MCP; local stdio on Windows, Remote MCP for remote agents.

Verify it worked

• A run connects over CDP and lands on a logged-in page without a fresh login flow.
• Stopping and restarting the profile preserves cookies and site state.
• The Local API list matches the agent-to-profile assignment you documented.
• No run leaves a browser process behind after stop.

Cautions

• Agents must respect each site's terms, rate limits, and robots rules; a persistent login makes automation visible and attributable.
• Do not point agents at accounts whose loss would hurt you; use dedicated accounts with minimal privileges.
• Parallel runs on one profile corrupt session state — serialize runs per profile.