Build with Mimic.

Start the local browser runtime, connect a standard automation client over CDP, and configure the observable environment your workflow needs.

Getting started

Download the latest Windows or Linux archive from GitHub Releases, verify it against the included SHA256SUMS, and extract it. No Chrome, Go, Rust, display server, or GPU is required for the packaged executable.

# Windows
.\mimic.exe --listen 127.0.0.1:9222

# Linux
./mimic --listen 127.0.0.1:9222

Keep the process running while your client is connected. The endpoint has no authentication and is intended for trusted local clients.

Playwright

Install playwright-core so the client does not download a browser:

npm install playwright-core

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP("http://127.0.0.1:9222");
try {
  const context = browser.contexts()[0];
  const page = await context.newPage();
  await page.goto("https://example.com/", { waitUntil: "load" });
  console.log(await page.locator("h1").textContent());
} finally {
  // This disconnects the client; it does not own the Mimic process.
  await browser.close();
}

Wait for an application-specific element or state when hydration continues after the load event. Supported workflows include locators, forms, fetch-driven DOM updates, frames, Shadow DOM, popups, cookies, history, multiple Pages, and network events; this is not a promise that every Playwright feature is available.

Puppeteer

npm install puppeteer-core@25.10.0

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserURL: "http://127.0.0.1:9222",
  defaultViewport: null
});
const page = await browser.newPage();
await page.goto("https://example.com/", { waitUntil: "load" });
console.log(await page.$eval("h1", node => node.textContent));
await page.close();
await browser.disconnect();

CLI reference

Environment profiles

Schema version 1 configures a BrowserContext before its first page loads. Pages, frames, and new workers inherit the Context environment. Full replacement requires a new Context; existing cookies, documents, and JavaScript are not migrated.

{
  "schemaVersion": 1,
  "baseProfile": "chrome-152-windows-x64-headful-controlled-v1",
  "display": { "width": 1920, "height": 1080, "deviceScaleFactor": 1 },
  "window": { "viewportWidth": 1280, "viewportHeight": 720 },
  "hardware": { "logicalProcessors": 8, "deviceMemoryGB": 8 },
  "locale": {
    "languages": ["en-US", "en"],
    "timezone": "America/New_York",
    "intlLocale": "en-US"
  },
  "preferences": { "colorScheme": "dark", "reducedMotion": false }
}

Unknown fields, nulls, wrong types, and unsupported custom values return explicit validation errors. Objects merge named members into the base; arrays replace their complete value. Query Mimic.getProfileSchema for the exact base profile and machine-readable field contract.

Profile fields

Mimic.* commands

Send these custom commands through a browser or page CDP session. They supplement standard CDP; they are not a separate public JavaScript SDK.

Native proxies

{
  "network": {
    "proxy": {
      "server": "socks5://127.0.0.1:1080",
      "username": "user",
      "password": "password"
    }
  }
}

SOCKS5, HTTP, and HTTPS proxy URLs are supported. Keep credentials in separate fields and out of public files. A proxy failure never falls back to a direct connection. Proxy mode disables QUIC and routes resource-loader HTTP(S), including worker fetch; it does not route UDP/WebRTC.

Multiple contexts

const cdp = await browser.target().createCDPSession();
const { diagnostics } = await cdp.send("Mimic.validateProfile", { profile });
const { browserContextId } = await cdp.send("Mimic.createContext", {
  profile,
  disposeOnDetach: true
});
try {
  const { targetId } = await cdp.send("Target.createTarget", {
    browserContextId,
    url: "about:blank"
  });
  await cdp.send("Mimic.updateProfile", {
    targetId,
    patch: { window: { viewportWidth: 900, viewportHeight: 600 } }
  });
} finally {
  await cdp.send("Target.disposeBrowserContext", { browserContextId });
}

Set the complete profile before creating or navigating the target. A Context is a state boundary, not a security sandbox for hostile tenants.

Compatibility boundaries

Mimic models observable browser state without a native rendering pipeline. Use a full browser when pixels are the desired output.

• No screenshots, rendered PDFs, video playback, or Canvas/WebGL pixel output.
• Modeled geometry and input are not complete CSS layout, clipping, rich editing, touch, drag, or arbitrary transforms.
• CDP and Web API coverage is partial. Generated names and wire schema do not imply implemented semantics.
• Compatibility checks describe specific workflows—not every website, client option, or anti-bot decision.
• The CDP endpoint has no authentication; bind it only where trusted clients can reach it.

Troubleshooting

The client cannot connect

Confirm Mimic prints its listening URL, keep the process alive, and use the same HTTP origin in connectOverCDP or browserURL. Avoid exposing the unauthenticated endpoint publicly.

The application loaded but is not ready

The browser load event can precede hydration. Wait for a selector, text, or application state that represents readiness instead of relying only on waitUntil: "load".

A command is unsupported

Query Mimic.getCompatibilityMatrix and reduce the workflow to the command and observable behavior it needs. A command accepted for client initialization may still have an explicit unsupported boundary.

Linux text geometry differs

Install Liberation, DejaVu, or Noto fonts. Exact Windows text metrics require matching legally available reference fonts.

FAQ

Is Mimic headless Chrome?

No. It uses V8 for JavaScript but does not embed or launch Chromium.

Does every website work?

No. Compatibility is actively expanding and depends on the APIs, loading behavior, and interactions a workflow uses.

Can I run untrusted code?

No. Mimic is not a security sandbox, and separate Pages are not hostile-tenant security boundaries.

Is Mimic open source?

Implementation sources remain private. The public overview, benchmarks, and MIT-licensed client examples are available on GitHub. Mimic uses PolyForm Shield 1.0.0.