Tokenade

Portable browser sessions. Export cookies (and storage) from a real browser into a .tokenade file, then launch or proxy on another machine as that session — with TLS fingerprint matching where it matters.

pip install tokenade
tokenade plugin sync

Not a Multilogin / AdsPower replacement. Tokenade is session portability (export → package → inject / proxy), not a full anti-detect browser product. Stealth is best-effort and measured — never “undetectable.”

Why Tokenade?

Self-hosted CLI. No cloud account required for the core loop.

Quick start

1. Install

pip install tokenade
# Python 3.10+

Optional extras: tokenade[tui], tokenade[linux], tokenade[enterprise] (LDAP — experimental).

2. Install site plugins + quit the donor browser

tokenade plugin sync
tokenade export --list-handlers

Fully quit the browser first (see Best practices). A running browser locks the cookie database.

tokenade export --list-profiles

# Hard sites use dedicated handlers that export required storage origins.
tokenade export --browser-name firefox --plugin discord-handler -o discord.tokenade

3. Use the session

Load into CloakBrowser (default automation backend):

tokenade load --file discord.tokenade

Show a browser window when needed:

tokenade load --file discord.tokenade --visible

Proxy (CDP reverse proxy with optional TLS impersonation):

tokenade proxy -s gmail.tokenade
# Open the local GUI / URL printed by the CLI (default port 9222)

Encrypt sensitive jars before sharing or storing:

tokenade encrypt -i discord.tokenade -o discord.tokenade.enc -p "my-secret"
# or: tokenade export ... --encrypt-password '…'

Full command list: tokenade --help and tokenade <command> -h. Start with docs/USER_GUIDE.md; release hardening work is tracked in docs/RELEASE_HARDENING.md.

What works (evidence-based)

GitHub/Discord/Reddit from session-only cookies often fail when the donor never wrote durable auth cookies to disk.

Core workflows

┌──────────────┐     export      ┌────────────────┐     launch / proxy
│ Donor browser│ ──────────────► │ .tokenade file │ ──────────────────► Target
│ (logged in)  │  cookies (+LS) │  portable jar  │  clean profile or CDP
└──────────────┘                 └────────────────┘

1. Export — read cookies and handler-declared storage from a real profile; package as .tokenade.
2. Transfer — copy the file (optionally encrypted) to another machine or process.
3. Replay — load (CloakBrowser + inject), launch (system browser + inject), or proxy (TLS-matched reverse proxy).

Google recipe (verified): donor not Chrome → target Brave / Edge / Firefox → clean --profile-dir → open the product URL (e.g. mail.google.com), not accounts.google.com after inject. Same jar can run on multiple non-Chrome browsers/devices concurrently. Vivaldi is code-supported but not battle-tested.

Best practices

These matter more than flag trivia. Follow them and most “broken session” reports go away.

Export

1. Fully quit the donor browser before export. Chrome/Firefox/Brave hold exclusive locks on the cookies SQLite DB. “Quit” means no residual process in Task Manager / Activity Monitor / pgrep. Otherwise you get database is locked or a partial/stale dump.
2. Export only the domains you need (--domains or a site plugin). Smaller jars are easier to reason about and safer to share.
3. Prefer a stable donor for high-value accounts. For Google, prefer Firefox / Brave / Edge — not Google Chrome — so cookies are portable.
4. Use --list-profiles when multiple profiles exist; export the one that is actually logged in.
5. Encrypt before sharing (encrypt or --encrypt-password). Treat .tokenade like a password dump.
6. Need storage (Discord, Telegram, some SPAs)? Prefer a site handler. Handlers can declare exact storage origins, so export captures the right localStorage automatically.

Launch & inject

7. Always use a clean --profile-dir for tests and portability. Injecting into a dirty system profile mixes old cookies, risk signals, and false failures.
8. Navigate to the product URL, not the IdP bounce page, after inject (e.g. inbox URL, not accounts.google.com).
9. Google: avoid Chrome-family targets (Chrome, Chromium, Canary). Non-Chrome targets work; Chrome clean profiles still fail in practice.
10. One CDP port per concurrent browser (--port). Parallel launches need distinct ports and profile dirs.
11. Site plugins (--plugin discord-handler, --plugin telegram-handler, --plugin generic-handler) keep domain filters and storage rules consistent between export and load.

Proxy & ops

12. Prefer 127.0.0.1 binding for local proxy; do not expose session proxies to the network without deliberate network design.
13. TLS fingerprint / --fingerprint: useful for many anti-bot stacks; can interfere with some cf_clearance flows — verify per site.
14. Refresh instead of re-login when cookies age: tokenade refresh-browser or tokenade accounts refresh for batches.
15. Health is a hint, not a login proof. tokenade health scores cookie heuristics; confirm with a real page load when it matters.
16. Do not commit live .tokenade files to git. Add them to .gitignore; rotate if leaked.

Security habits

17. Session files = full account access for cookie lifetime. Store encrypted; limit filesystem permissions.
18. Prefer short-lived copies on shared machines; delete profile dirs under /tmp when done.
19. For automation, pin Python and document the donor browser version you validated against.

Installation (dev)

git clone https://github.com/mihir0209/tokenade.git
cd tokenade
pip install -e ".[dev]"
playwright install chromium --with-deps
pytest   # suite under tokenade/tests/

CloakBrowser (stealth Chromium backend) is a core dependency; its binary downloads on first use when available.

Plugins

Site handlers and other plugins customize domains, critical cookies, and launch behavior without forking core:

tokenade export --list-handlers
tokenade plugin list
tokenade launch -s gmail.tokenade --plugin google-handler --browser brave \
  --profile-dir /tmp/tokenade-brave-clean --visible

Authoring guide: docs/PLUGIN_DEVELOPMENT.md. Examples: examples/plugins/.

Request framework

For automation and orchestration, Tokenade accepts a nested request.json envelope. The core validates structure only; plugin config is dynamic pass-through.

Run operation

Execute plugin operations in order:

{
  "version": "1",
  "operation": "run",
  "plugins": [
    {
      "name": "generic-handler",
      "required": true,
      "roles": {
        "run": {
          "method": "process"
        }
      },
      "config": {
        "session_file": "/path/to/github.tokenade",
        "site": "github"
      }
    }
  ],
  "execution": {
    "stop_on_error": true
  }
}

tokenade run --request request.json

Gateway operation

Start a local multi-session control plane with isolated browser contexts:

{
  "version": "1",
  "operation": "gateway",
  "sessions": {
    "dir": "./sessions",
    "pattern": "*.tokenade"
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 9222,
    "backend": "cdp"
  },
  "routing": {
    "object": "session",
    "strategy": "health-weighted",
    "switch_interval_seconds": 30,
    "sticky_by": "site",
    "failover": true,
    "drain_existing_tabs": true
  },
  "plugins": []
}

tokenade gateway --request request.json

Gateway API endpoints:

• GET /status — routing state and session count
• GET /sessions — sanitized session records (no cookies/storage)
• POST /route/next — select next session by strategy
• POST /route/select — set active session by ID/path/site
• GET /contexts — isolated browser context state
• POST /contexts/prewarm — prewarm contexts for sessions
• POST /contexts/drain — close inactive contexts
• POST /tabs/new — open new tab on active context

Privacy: gateway outputs session metadata only (site, cookie count, health score). Never cookies, tokens, localStorage, or proxy credentials.

Proxy resolve operation

Resolve upstream proxy provider configuration with credential redaction:

{
  "version": "1",
  "operation": "proxy.resolve",
  "plugins": [
    {
      "name": "brightdata",
      "required": true,
      "roles": {
        "proxy_provider": {
          "mode": "sticky",
          "nearest_to_source": true,
          "fallback": "fail"
        }
      },
      "config": {
        "zone": "residential"
      }
    }
  ]
}

tokenade proxy resolve --request request.json

Output is redacted by default. Use --show-secrets to reveal credentials.

Security (short)

• Treat every .tokenade as credentials.
• Use encryption at rest; prefer encrypt-on-export for transfers.
• Default proxy bind is loopback; SSRF protections block private/loopback targets on outbound proxy paths.
• Report security issues privately when possible; see docs/SECURITY.md.

Documentation

CLI discovery beats a second manual: tokenade --help.

Project stance

• Honesty over hype — battle-tested vs “code exists” stay separated in docs and messaging.
• Session portability first — plugins, stealth, fleet tooling support that core; they are not the product by themselves.
• Evidence — Google multi-device non-Chrome recipe verified 2026-07-10; see project notes under .agent/ for campaign details (not required for end users).

License

MIT — Copyright (c) 2026 MiHiR