mvanhorn/agentcookie

agentcookie – Sync Chrome cookies from your Mac to a Linux agent

What it does

• Continuously watches the Chrome Cookies SQLite file on macOS, decrypts it using the macOS Keychain, and sends any changes over an encrypted Tailscale channel to a Linux machine where an automation agent runs.
• On the Linux side the cookies are injected live into Chrome’s in‑memory store via the Chrome DevTools Protocol (CDP), so any script that uses Puppeteer, Playwright, or a raw CDP connection sees the same logged‑in session as you have on your Mac.
• No manual copy‑paste of cookie strings, no extra login steps, and no need to rewrite Chrome’s on‑disk SQLite database on the Linux box.

Why it matters

• Many AI/automation agents (e.g., Grok Bot, custom bots, scraping tools) run on headless Linux VMs. They often need to act as a logged‑in user on sites that you are already signed into on your desktop. agentcookie automates that bridge securely and unattended.
• Uses AES‑256‑GCM encryption and per‑peer keys derived from a Tailscale pairing ceremony, so only the intended sink can read the cookies.
• Handles macOS‑specific protections (Keychain, Chrome’s app‑bound encryption) for the source side, and leverages CDP for safe injection on the sink side.

How it works (high‑level flow)

1. Source (macOS) – agentcookie source --watch watches the Chrome Cookies file, reads it read‑only, decrypts with the Keychain, applies a configurable cookie policy, wraps the data in a sealed envelope, and sends it over HTTPS on the Tailscale network.
2. Sink (Linux) – agentcookie sink listens on a Tailscale address, decrypts the envelope, re‑applies its own policy, and calls Storage.setCookies via CDP to put the cookies into Chrome’s live store.
3. Live CDP injection – No SQLite rewrite on Linux; cookies appear instantly in any new tab or headless browser context.

Key components

• Pairing wizard – Generates a one‑time code and URL; both sides exchange public keys over the Tailscale tailnet.
• Policy files – blocklist.yaml (default empty on Linux, meaning ship nothing) or allowlist.yaml to restrict which domains are synced.
• Configuration – YAML files under ~/.config/agentcookie/ for source, sink, and optional multi‑sink setups.
• CLI commands – wizard install, pair, source, sink, doctor, status.

Typical setup

1. Install the binary (or go install) on both Mac and Linux.
2. Run the source wizard on the Mac, note the pairing code.
3. Create a sink config on the Linux box (or use the wizard on macOS sinks) and pair with the code.
4. Start Chrome on Linux with --remote‑debugging‑port=9223 (or let the wizard detect an existing instance).
5. Run agentcookie sink (or a systemd user service) and watch the sync happen.

Security notes

• Communication is encrypted end‑to‑end; the Tailscale WireGuard channel adds another layer.
• Linux sinks default to an empty blocklist, so nothing is sent unless you explicitly allow it.
• Device‑Bound Session Credentials (DBSC) used by Google/Workspace only work for a short window on the sink; you still need to sign into Google on the Linux Chrome once.
• The plaintext side‑car file (~/.agentcookie/cookies‑plain.db) stores cookies unencrypted – treat it as a temporary cache; the primary security guarantee is the live CDP injection.

Limitations

• Only one‑way sync (Mac → Linux). Reverse sync isn’t implemented.
• DBSC‑protected cookies expire quickly on the sink; they must be re‑authenticated locally.
• No live key rotation yet – you must re‑run the wizard to generate new keys.
• Multi‑sink fan‑out is supported, but every sink receives the full cookie set, so trust is required.

Where to learn more

• Architecture details: docs/architecture.md
• Wire‑format spec: docs/protocol.md
• Threat model: docs/threat-model.md
• Quick‑start guide: docs/quickstart.md

License – MIT.

---

agentcookie is a practical tool for anyone running automation agents on a headless Linux box who wants to reuse their existing Chrome login state without manual cookie handling, all while keeping the data encrypted and scoped to the machines on their private Tailscale network.