# agentcookie Documentation > Reference for the peer-to-peer macOS daemon that replicates Chrome cookies and per-CLI secrets from a logged-in laptop to an agent's second Mac over a Tailscale tailnet. ## Context Links - [Agent index](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/llms.txt) - [Human interactive docs](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae) - [GitHub repository](https://github.com/mvanhorn/agentcookie) ## Repository Metadata - Repository: mvanhorn/agentcookie - Generated: 2026-06-01T03:16:41.694Z - Updated: 2026-06-01T03:20:26.881Z - Runtime: Claude Code - Format: Documentation - Pages: 24 ## Page Index - 01. [Overview](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/01-overview.md) - What agentcookie replicates between two Macs, the three cookie delivery surfaces, the parallel secrets bus, and the shortest source-backed path through these docs. - 02. [Installation](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/02-installation.md) - Prerequisites (Tailscale, Chrome, Go 1.22+), `go install` of the unified CLI, and the `agentcookie wizard install` flow that drops configs, pairs, and installs the LaunchAgent. - 03. [Quickstart](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/03-quickstart.md) - Five-minute laptop + second-Mac pairing: drop configs, run `agentcookie pair`, start the sink LaunchAgent, push from source, and verify with `agentcookie status`. - 04. [Headless second-Mac install](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/04-headless-second-mac-install.md) - SSH-only install on a sink with no GUI session: degraded-mode fallback, the one-password Safe Storage open, and the `wizard set-keychain-access` upgrade path. - 05. [Source and sink topology](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/05-source-and-sink-topology.md) - The one-way laptop-to-second-Mac model: the source watcher, the sink listener, the role split, and what each side reads and writes. - 06. [Cookie delivery surfaces](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/06-cookie-delivery-surfaces.md) - The three sink-side delivery paths: real Chrome Default profile via Safe Storage, the plaintext sidecar at `~/.agentcookie/cookies-plain.db`, and per-CLI adapter session files. - 07. [Secrets bus](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/07-secrets-bus.md) - How bearer tokens, API keys, and KEY=VALUE auth blobs ride the same encrypted push, land at `~/.agentcookie/secrets//secrets.env`, and the v2 adoption tiers (explicit manifest, PP-CLI auto, legacy v1). - 08. [Pairing and per-peer keys](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/08-pairing-and-per-peer-keys.md) - X25519 + HKDF-SHA256 handshake, the base32 pairing code, the per-peer key file at `~/.config/agentcookie/keys/.json`, rate-limiting on `/pair`, and the sealed master key. - 09. [Device-bound cookies (DBSC)](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/09-device-bound-cookies-dbsc.md) - How agentcookie detects DBSC-suspect cookies, the default warn-and-ship behavior, and the `--skip-dbsc-suspect` / `AGENTCOOKIE_SKIP_DBSC_SUSPECT` drop path. - 10. [Configure source and sink](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/10-configure-source-and-sink.md) - Editing `source.yaml` and `sink.yaml`: sink URL, listen address validation (tailnet-only), peer hostname, Chrome DB path, CDP managed-Chrome toggle, and `skip_chrome_sqlite` for headless boxes. - 11. [Enable universal cookie delivery](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/11-enable-universal-cookie-delivery.md) - The one-login-password Safe Storage open, the `teamid:` partition list, duplicate-Keychain-item convergence, and unsigned-CGO boundary so any unmodified cookie tool reads the synced Default profile. - 12. [Adopt a CLI with agentcookie.toml](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/12-adopt-a-cli-with-agentcookie.toml.md) - Authoring a v2 adoption manifest, declaring `[secrets]`, aliases, and `[[files]]`, running `agentcookie discover`, and migrating from imperative `secret import-from` to manifest-driven sync. - 13. [Write a cookie adapter](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/13-write-a-cookie-adapter.md) - The ~50-line pattern for a new sink adapter: `Register()` into the adapter registry, the validate hook, the seal helper, and the five built-in PP-CLI adapters as templates. - 14. [Drive install from an agent](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/14-drive-install-from-an-agent.md) - Using the bundled Claude Code skill to install agentcookie on source + sink unattended: required inputs, the SSH-driven flow, success signals, and error recovery. - 15. [CLI reference](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/15-cli-reference.md) - Every `agentcookie` subcommand and its flags: `source`, `sink`, `pair`, `wizard`, `doctor`, `status`, `secret`, `discover`, `cookies`, `version`. - 16. [Configuration files reference](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/16-configuration-files-reference.md) - Schemas and validation rules for `source.yaml`, `sink.yaml`, `allowlist.yaml`, and `blocklist.yaml` (SQLite LIKE patterns, tilde expansion, listen-address checks). - 17. [agentcookie.toml manifest reference](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/17-agentcookie.toml-manifest-reference.md) - The v2 adoption manifest schema: `schema_version`, `[secrets]`, `[aliases]`, `[[files]]`, project kinds, discovery roots, and the three integration tiers. - 18. [Wire protocol v1](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/18-wire-protocol-v1.md) - HTTP-over-Tailscale POST `/sync`, AES-256-GCM seal, `SyncEnvelope` JSON fields, sink validation order, and the response semantics (401/400/409). - 19. [Secrets bus on-disk layout](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/19-secrets-bus-on-disk-layout.md) - The v1 standard layout under `~/.agentcookie/secrets//`, file modes (0600), `secrets.env` format, optional sealed twin, and the `[[files]]` materialization path. - 20. [pkg/agentcookiesecret reader library](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/20-pkg-agentcookiesecret-reader-library.md) - In-process Go API for consuming the secrets bus from a CLI: `Load`, key resolution rules, refresh semantics, and how a CLI uses it instead of shelling out. - 21. [doctor and adapter verification](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/21-doctor-and-adapter-verification.md) - The fifteen `agentcookie doctor` check categories, the `DoctorReport` JSON envelope, `wizard verify-adapters` output, and exit-code semantics for agent consumption. - 22. [LaunchAgent management](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/22-launchagent-management.md) - How `wizard install` writes `dev.agentcookie.source` / `dev.agentcookie.sink` plists, bootstrap with `launchctl`, log paths, and the v0.9 soup-to-nuts lifecycle. - 23. [Release, signing, and notarization](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/23-release-signing-and-notarization.md) - The goreleaser pipeline, the `sign.sh` / `notarize.sh` / `release-tarball.sh` scripts, Developer ID signing for `teamid:` partition trust, and CI secret renewal. - 24. [Troubleshooting](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/24-troubleshooting.md) - Common failures and recovery: pairing `connection refused`, sink Keychain prompts, missing `~/go/bin` on the sink, stale Chrome `SingletonLock`, DBSC-suspect drops, and the FAQ. ## Source File Index - `.goreleaser.yaml` - `CHANGELOG.md` - `cmd/agentcookie/main.go` - `docs/architecture.md` - `docs/consumption.md` - `docs/faq.md` - `docs/protocol.md` - `docs/quickstart-beta.md` - `docs/quickstart.md` - `docs/runbook-adoption-manifest-author.md` - `docs/runbook-secrets-bus-adoption.md` - `docs/runbook-secrets-bus-gh-example.md` - `docs/runbook-v0.10-keychain-access.md` - `docs/runbook-v0.11-adapter-cookie-push.md` - `docs/runbook-v0.12-codesign.md` - `docs/runbook-v0.12-security-hardening.md` - `docs/runbook-v0.13-one-password-keychain.md` - `docs/runbook-v0.9-soup-to-nuts.md` - `docs/spec-agentcookie-secrets-bus-v1.md` - `docs/spec-agentcookie-secrets-bus-v2-adoption.md` - `docs/threat-model.md` - `examples/adoption-last30days/agentcookie.toml` - `examples/adoption-third-party-cli/agentcookie.toml` - `examples/allowlist.yaml` - `examples/blocklist.yaml` - `examples/gh-shim/gh` - `examples/launchd-sink.plist` - `examples/sink.yaml` - `examples/source.yaml` - `internal/chrome/dbsc_test.go` - `internal/chrome/dbsc.go` - `internal/chrome/keychain_keybase.go` - `internal/chrome/keychain.go` - `internal/chrome/launchagent_helper.go` - `internal/chrome/sidecar.go` - `internal/chrome/write.go` - `internal/cli/cookies.go` - `internal/cli/discover.go` - `internal/cli/doctor.go` - `internal/cli/httpserver/httpserver.go` - `internal/cli/login_password.go` - `internal/cli/pair.go` - `internal/cli/root.go` - `internal/cli/secret_coverage.go` - `internal/cli/secret.go` - `internal/cli/sink.go` - `internal/cli/source.go` - `internal/cli/status.go` - `internal/cli/wizard_keychain.go` - `internal/cli/wizard_verify_adapters.go` - `internal/cli/wizard.go` - `internal/config/allowlist.go` - `internal/config/config.go` - `internal/keystore/keystore.go` - `internal/keystore/master.go` - `internal/keystore/seal.go` - `internal/launchd/plist.go` - `internal/pairing/pairing.go` - `internal/pairing/ratelimit.go` - `internal/protocol/allowlist.go` - `internal/protocol/envelope.go` - `internal/protocol/sequence.go` - `internal/secretsbus/discovery.go` - `internal/secretsbus/filecarriage.go` - `internal/secretsbus/manifest_v2.go` - `internal/secretsbus/pp_cli_adapter.go` - `internal/secretsbus/secretsbus.go` - `internal/secretsbus/writer.go` - `internal/sinkpush/adapter_airbnb.go` - `internal/sinkpush/adapter_instacart.go` - `internal/sinkpush/adapter_tablereservation.go` - `internal/sinkpush/adapter.go` - `internal/sinkpush/init.go` - `internal/sinkpush/registry.go` - `internal/sinkpush/seal.go` - `internal/state/state.go` - `internal/transport/crypto.go` - `internal/watcher/watcher.go` - `Makefile` - `pkg/agentcookieadoption/adoption.go` - `pkg/agentcookiesecret/doc.go` - `pkg/agentcookiesecret/load_test.go` - `pkg/agentcookiesecret/load.go` - `pkg/sidecar/reader.go` - `README.md` - `scripts/install-beta.sh` - `scripts/notarize.sh` - `scripts/release-tarball.sh` - `scripts/sign.sh` - `skill/prompts/install-on-both-machines.md` - `skill/SKILL.md` --- ## 01. Overview > What agentcookie replicates between two Macs, the three cookie delivery surfaces, the parallel secrets bus, and the shortest source-backed path through these docs. - Page Markdown: https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/01-overview.md - Generated: 2026-06-01T03:00:51.240Z ### Source Files - `README.md` - `docs/architecture.md` - `cmd/agentcookie/main.go` - `internal/cli/root.go` - `CHANGELOG.md` --- title: "Overview" description: "What agentcookie replicates between two Macs, the three cookie delivery surfaces, the parallel secrets bus, and the shortest source-backed path through these docs." --- agentcookie is a macOS-only daemon and CLI that one-way-replicates Chrome session state and per-CLI auth secrets from a "source" Mac (the laptop you log in on) to a "sink" Mac (where agents act on your behalf). The source watches Chrome's `Cookies` SQLite with `fsnotify`, decrypts each row with the local Keychain-backed Safe Storage key, wraps the result in a versioned `SyncEnvelope`, AES-256-GCM-seals it under a per-peer pairing key, and POSTs it over the Tailscale tailnet to the sink's `/sync` endpoint. The sink validates the envelope, then fans the payload out across three cookie delivery surfaces and a parallel secrets bus so any unmodified or agentcookie-aware tool can read the synced session. The unified entry point is `cmd/agentcookie/main.go`, which dispatches to the cobra tree wired in `internal/cli/root.go`: `source`, `sink`, `pair`, `status`, `version`, `wizard`, `doctor`, `secret`, `discover`, `cookies`. Configuration lives under `~/.config/agentcookie/` (`source.yaml`, `sink.yaml`, `allowlist.yaml`); paired per-peer keys live at `~/.config/agentcookie/keys/.json` mode `0600`; sink-side runtime state lives under `~/.agentcookie/`. ## What agentcookie replicates | Surface on source | Carried in envelope | Surface on sink | |---|---|---| | Chrome `Cookies` SQLite (Default profile, decrypted via macOS Keychain Safe Storage) | Filtered + sealed cookie set | Re-encrypted into sink Chrome `Cookies` + plaintext sidecar + per-CLI adapter files | | `~/.agentcookie/secrets//secrets.env` (mode `0600`, watched by `fsnotify`) | Per-CLI `KEY=VALUE` secrets payload | Mirrored to identical path on sink; optional sealed twin under v0.12 master key | | `agentcookie.toml` manifests discovered under user dirs and project roots | Materialized `[[files]]` blobs | Files materialized at declared `env`/path on sink | The push is one-way: source → sink. There is no merge, no destination prompt, no GUI click after install. Filtering happens on both sides via `allowlist.yaml`, and a `SequenceTracker` in sink memory rejects equal-or-lower envelope sequences. ## Sync lifecycle ```mermaid sequenceDiagram autonumber participant Chrome as Chrome (source Mac) participant Bus as secrets bus
(~/.agentcookie/secrets) participant Src as agentcookie source
(LaunchAgent watcher) participant Net as Tailscale tailnet
(AES-256-GCM over HTTP) participant Sink as agentcookie sink
(LaunchAgent on :9999) participant Out as Sink delivery surfaces Chrome-->>Src: fsnotify(Cookies SQLite) + debounce Bus-->>Src: fsnotify(secrets.env) + manifest scan Src->>Src: read SQLite RO, decrypt Safe Storage,
filter by allowlist, build SyncEnvelope (v1) Src->>Net: POST /sync (sealed with per-peer key) Net->>Sink: deliver bytes Sink->>Sink: open seal (401 on key mismatch)
check ProtocolVersion==1 (400)
check Sequence (409 on replay)
filter against sink allowlist Sink->>Out: 1) Chrome SQLite (re-encrypt with sink key) Sink->>Out: 2) ~/.agentcookie/cookies-plain.db sidecar Sink->>Out: 3) per-CLI adapter session files Sink->>Out: 4) ~/.agentcookie/secrets//secrets.env ``` ## The three cookie delivery surfaces The sink runs all three after every successful sync; consumers pick the surface that matches how they read cookies. Re-encrypts each cookie under the sink's Chrome Safe Storage key and upserts into the sink's `Cookies` SQLite (schema-aware INSERT … ON CONFLICT). At install, one login-password entry opens Safe Storage for the `apple-tool:`, `apple:`, and `teamid:` partitions so any unmodified cookie reader (yt-dlp, gallery-dl, browser-driving agents) sees a logged-in Default profile. This is the universal default. Decrypted cookies written to `~/.agentcookie/cookies-plain.db` for agentcookie-aware consumers that prefer not to touch Chrome. Toggleable via `AGENTCOOKIE_PLAIN_COOKIES`. Works in degraded mode when no Keychain password is available. Built-in adapters write the shape each PP CLI expects: `instacart` and `table-reservation-goat` → `session.json`; `airbnb`, `ebay`, `pagliacci` → `config.toml` + `cookies.json`. New adapters are ~50 lines plus a `Register()` call. ## The parallel secrets bus Bearer tokens, API keys, and other `KEY=VALUE` auth blobs ride the same encrypted push the cookies do. On the sink they land at: ```text ~/.agentcookie/secrets/ / secrets.env # mode 0600, KEY=VALUE per line secrets.env.sealed # optional twin under the v0.12 master key manifest.toml # optional per-key sync overrides ``` Three adoption tiers coexist for opting a CLI into bus-driven sync: | Tier | How it works | When to use | |---|---|---| | explicit-manifest | Drop `agentcookie.toml` with `[secrets]`, `[aliases]`, `[[files]]`; `agentcookie discover` picks it up | First-class adoption for new or external CLIs | | pp-cli-derived | Auto-synthesized in memory from a CLI's existing `.printing-press.json` (`auth_env_var_specs`) | Printing Press CLIs that ship today with no manifest | | legacy-v1 | Existing `~/.agentcookie/secrets//` directories continue to work; `agentcookie secret import-from` still imports JSON/TOML/env into the standard layout | Pre-v2 setups; ad-hoc imports | Consumers read the bus three ways: shell env (`eval "$(agentcookie secret env )"`), the in-process Go library `pkg/agentcookiesecret`, or a CLI's own `agentcookie.toml` `[[files]]` materialization. ## Security boundaries at a glance | Boundary | Enforced by | |---|---| | Cookie value at rest | Chrome Safe Storage per-machine AES key + Keychain ACL | | Cookie value in transit | AES-256-GCM with per-peer pairing key + Tailscale WireGuard | | Pairing authenticity | X25519 + HKDF-SHA256 with the base32 pairing code mixed into the salt | | Listener exposure | Tailnet-only bind validation in `sink.yaml`; pair endpoint rate-limited with a 64-bit code | | Replay defense | Monotonic `Sequence` checked by sink `SequenceTracker` (HTTP 409 on regress) | | Protocol stability | `ProtocolVersion` field on every envelope (HTTP 400 on mismatch) | | File mode discipline | `0600` on `keys/*.json`, `secrets.env`, sealed twins | For device-bound cookies (DBSC), the source flags suspect rows and by default ships them with a warning; pass `--skip-dbsc-suspect` or set `AGENTCOOKIE_SKIP_DBSC_SUSPECT=1` to drop them. The secrets bus is untouched by DBSC. ## What's in the box | Command | Role | |---|---| | `agentcookie source` | Long-lived watcher or `--once` push from the laptop | | `agentcookie sink` | Long-lived `/sync` listener on the second Mac | | `agentcookie pair` | X25519 + HKDF pairing handshake | | `agentcookie wizard install` | Drops configs, pairs, installs LaunchAgents, opens Safe Storage | | `agentcookie doctor` | Fifteen health categories; `--json` for agents | | `agentcookie status` | Last sync, sequence, peer state | | `agentcookie secret` | `list`/`get`/`set`/`rm`/`revoke`/`import-from`/`env` | | `agentcookie discover` | Walk for `agentcookie.toml` manifests | | `agentcookie cookies` | Inspect the synced cookie store | | `agentcookie version` | Linked-in `Version` string | ```text cmd/agentcookie/ CLI entry (cobra) internal/cli/ Subcommand implementations internal/chrome/ Read + decrypt + schema-aware write of Chrome Cookies internal/cdp/ Chrome DevTools Protocol client (Storage.setCookies) internal/transport/ AES-GCM seal/open internal/pairing/ X25519 + HKDF pairing handshake internal/keystore/ Per-peer key file management internal/protocol/ SyncEnvelope, SequenceTracker, AllowlistMatcher internal/config/ YAML loaders (source.yaml, sink.yaml, allow/blocklist) internal/secretsbus/ fsnotify watcher + on-disk layout for secrets internal/sinkpush/ Adapter registry + delivery fan-out internal/launchd/ LaunchAgent plist generation + bootstrap internal/tsclient/ Tailscale tailnet checks internal/watcher/ Debounced fsnotify for cookies + secrets pkg/agentcookiesecret/ In-process Go reader for the bus ``` ```text ~/.config/agentcookie/ source.yaml sink URL, peer hostname, watch options sink.yaml listen address, Chrome paths, sealing posture allowlist.yaml SQLite-LIKE host patterns blocklist.yaml negative patterns keys/.json per-peer pairing key (mode 0600) ~/.agentcookie/ cookies-plain.db plaintext cookie sidecar secrets// secrets.env KEY=VALUE per line (mode 0600) secrets.env.sealed optional sealed twin manifest.toml optional per-key overrides ``` ## Source-backed paths through these docs Prereqs, `go install`, and the `agentcookie wizard install` flow that pairs both sides and installs LaunchAgents. Configs + pair + push + verify with `agentcookie doctor`. SSH-only install, degraded-mode fallback, and the `wizard set-keychain-access` upgrade path. The one-way model, role split, and what each side reads and writes. The three sink-side delivery paths in depth. How bearer tokens, API keys, and KEY=VALUE blobs ride the push. X25519 + HKDF-SHA256 handshake and the per-peer key files. Detection, default warn-and-ship, and `--skip-dbsc-suspect`. `SyncEnvelope`, sink validation order, and 401/400/409 semantics. Every `agentcookie` subcommand and its flags. Schemas for `source.yaml`, `sink.yaml`, `allowlist.yaml`, `blocklist.yaml`. Pairing `connection refused`, sink Keychain prompts, stale `SingletonLock`, DBSC-suspect drops. ## Status snapshot Working today on macOS for both ends: continuous laptop-to-second-Mac sync with debounced `fsnotify`; the three cookie delivery surfaces; the secrets bus with sealed twin; v2 adoption manifests and `agentcookie discover`; tailnet-only listeners and rate-limited pairing; persistent replay defense; Developer ID signed binaries with `teamid:` partition trust; headless SSH install with degraded-mode fallback; fifteen-category `doctor`; 520+ unit tests across 26 packages. Not yet shipping: a Python reader at `clients/python/agentcookie_secret`, manifest signature verification (`signed_by` reserved for v2.1), `[secrets.command]` / `[secrets.keychain]` source kinds, `agentcookie pair --rotate` (re-run `wizard install` instead), and many-sink fan-out. ## Next Prereqs and `go install` flow. Five-minute laptop + second-Mac pairing. Mental model for the one-way replication. Every subcommand and flag. --- ## 02. Installation > Prerequisites (Tailscale, Chrome, Go 1.22+), `go install` of the unified CLI, and the `agentcookie wizard install` flow that drops configs, pairs, and installs the LaunchAgent. - Page Markdown: https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/pages/02-installation.md - Generated: 2026-06-01T03:01:57.632Z ### Source Files - `README.md` - `internal/cli/wizard.go` - `internal/cli/wizard_keychain.go` - `scripts/install-beta.sh` - `Makefile` --- title: "Installation" description: "Prerequisites (Tailscale, Chrome, Go 1.22+), `go install` of the unified CLI, and the `agentcookie wizard install` flow that drops configs, pairs, and installs the LaunchAgent." --- `agentcookie` ships as a single Go binary (`github.com/mvanhorn/agentcookie/cmd/agentcookie`) installed identically on the source Mac and the sink Mac. Bringing a pair online is two commands: `go install ...@latest` to place the binary, then `agentcookie wizard install` on each side. The wizard drops `source.yaml` / `sink.yaml`, runs the pairing handshake (port `9998`), attempts the one-password Chrome Safe Storage open, and bootstraps the per-role LaunchAgent (`dev.agentcookie.source` / `dev.agentcookie.sink`) so all subsequent sync work runs unattended. ## Prerequisites The wizard refuses to write a permissive listener default — Tailscale must be running so it can pin a tailnet 100.x address before rendering YAML. Chrome is only strictly required on the source for cookie reads, but the install scripts also probe for it on the sink. Running and signed in on both Macs. The wizard calls `tsclient.RequireTailnetIP` to detect a 100.x address for the pairing listener (source) and the `/sync` listener (sink). A missing or unreachable Tailscale daemon causes `wizard install` to abort with `detect Tailscale 100.x address for ... listener`. Installed on the source — the source watcher reads `~/Library/Application Support/Google/Chrome/Default/Cookies` via the Chrome Safe Storage key. On the sink, Chrome is required only when universal delivery is in use (the default). Needed only when installing from source. Pre-built release tarballs (`agentcookie--darwin-arm64.tar.gz`) can be used instead via `scripts/install-beta.sh --tarball `. Source and sink both run macOS. The sink relies on macOS LaunchAgent + Keychain conventions; both sides use the macOS-only Chrome Safe Storage decrypt path. The README pins Go 1.22+ as the public floor; `go.mod` currently targets `go 1.26.2`. Use a recent toolchain (`go install` will fetch a matching one when required) or install from a release tarball to skip the toolchain entirely. ## Install the binary Run on both Macs. `go install` deposits `agentcookie` in `$(go env GOBIN)` (default `$HOME/go/bin`). ```bash go install github.com/mvanhorn/agentcookie/cmd/agentcookie@latest ``` If `~/go/bin` is not on the sink's `PATH`, the LaunchAgent still works (it uses absolute paths) but `ssh sink 'agentcookie ...'` will report `command not found`. Add `export PATH="$HOME/go/bin:$PATH"` to the sink shell profile. ### Build from source The repo's `Makefile` provides a signing-aware local build for contributors and release builds: | Target | Result | |---|---| | `make build` | `go build -o bin/agentcookie ./cmd/agentcookie` | | `make install` | `go install ./cmd/agentcookie`, then `scripts/sign.sh "$(go env GOBIN)/agentcookie"` | | `make` / `make all` | Build + sign in `bin/agentcookie` | | `make release` | Build + sign + notarize (a portable binary that launches without prompts on any Mac) | | `make verify` | `codesign -d -r-` of the local build | | `make test` | `go test -race ./...` | `make sign` / `make notarize` require an Apple Developer ID. Override the identity via `AGENTCOOKIE_SIGN_IDENTITY`. Plain contributors can stop at `make build` + `make test` without a cert. ### Release tarball (beta installer) For closed-beta or air-gapped installs, `scripts/install-beta.sh` automates fetch + Gatekeeper / Developer ID verification + binary placement + wizard launch: ```bash ./install-beta.sh --as source # uses gh release download ./install-beta.sh --as sink --tarball ./bundle.tar.gz \ --code \ --pair-url http://:9998/pair ``` The script: - Checks Tailscale is up and the Chrome `.app` is installed. - Downloads `*darwin-arm64.tar.gz` via `gh release download` (or accepts `--tarball`). - Runs `codesign --verify --strict` and confirms the Developer ID OU is `NM8VT393AR`. - Places the binary in `/usr/local/bin/agentcookie` if writable, otherwise `$HOME/bin/agentcookie`. - Forwards `--peer`, `--code`, `--pair-url`, `--extra-binary`, `--skip-chrome-sqlite`, `--write-chrome-sqlite`, `--no-cdp`, and `--skip-keychain-prompt` to `agentcookie wizard install`. - Auto-adds `--skip-keychain-prompt` on a sink install when stdin is not a TTY. - Ends with `agentcookie doctor` so the operator sees the post-install health roll-up. ## Pair and install with the wizard `agentcookie wizard install` is the single command per machine. The source side runs first because it generates the pairing code the sink consumes. On the laptop you browse from: ```bash agentcookie wizard install --as source --peer ``` The source wizard, in order: 1. Validates `--as` (`source` or `sink`) and `--peer` (the OTHER machine's tailnet hostname). 2. Creates `~/.config/agentcookie/` (mode `0755`) and writes `source.yaml` + `blocklist.yaml` with `0600` perms if missing (use `--force` to overwrite an existing pair). `source.yaml` points at `http://:9999/sync` by default. 3. Refuses to proceed when an existing `source.yaml` has a `peer.hostname` that disagrees with `--peer` (the `guardConfigPeerMismatch` check; pass `--force` to overwrite). 4. Resolves a Tailscale 100.x address via `tsclient.RequireTailnetIP` and binds the pairing HTTP listener at `100.x.y.z:9998`. Plain `0.0.0.0`, `::`, and other any-interface binds are refused by `validateListenAddr`. 5. Prints the pairing code to stderr **and** writes a JSON sibling file `~/.agentcookie/pairing.json` so an SSH-driven agent can read the exact sink-side invocation: ```json { "code": "YILU-OIVK", "peer": "my-laptop", "pair_url": "http://100.x.y.z:9998/pair", "sink_run": "agentcookie wizard install --as sink --peer my-laptop --code YILU-OIVK --pair-url http://100.x.y.z:9998/pair" } ``` 6. Blocks until the sink connects, then saves the per-peer key at `~/.config/agentcookie/keys/.json` (filed under the operator-supplied `--peer`, not the sink's announced hostname). 7. Installs the `dev.agentcookie.source` LaunchAgent invoking the resolved binary with `--watch`. Logs land in `~/.agentcookie/logs/`. If a key for `--peer` already exists, the pairing step is skipped. Pass `--repair` to force a fresh handshake. On the second Mac: ```bash agentcookie wizard install --as sink \ --peer \ --code \ --pair-url http://:9998/pair ``` `--code` and `--pair-url` are required when `--as sink`. The sink wizard then: 1. Resolves the universal-vs-degraded delivery mode (see below) and runs the Chrome Safe Storage open BEFORE rendering `sink.yaml`, so a failure cleanly downgrades the rendered config. 2. Resolves the sink's tailnet 100.x address and writes `sink.yaml` with `listen.addr: 100.x.y.z:9999`, `peer.hostname: `, and the resolved `delivery:` marker (`universal` / `degraded`). 3. Runs `pairing.RunSink` against the source's `--pair-url`, derives the AES-256-GCM key, and saves `~/.config/agentcookie/keys/.json`. 4. Installs the `dev.agentcookie.sink` LaunchAgent. The daemon starts immediately under launchd. 5. Prints the optional Tailscale exit-node hint (`sudo tailscale set --exit-node= --exit-node-allow-lan-access=true`) and the cookie-bridge env-var hint. The wizard rejects `--code`/`--pair-url` mismatches at the `/pair` endpoint (HTTP 401), and the source's pair endpoint is rate-limited with a 64-bit code. Run on both Macs: ```bash agentcookie doctor agentcookie wizard verify-adapters ``` `doctor` walks fifteen health categories (binary signature, Tailscale, config, keystore, listener bind, sink/source state, sealing posture, adapter coverage, CDP injector, secrets-bus coverage, DBSC-suspect cookies). `verify-adapters` shows the per-adapter result of the last sync. ## Cookie delivery mode resolved at install On the sink, `resolveSinkHeadlessMode` + `resolveSinkDeliveryWithKeychain` decide what `sink.yaml` is rendered with and what runs against the Keychain. The v0.13 default is universal; degraded is the explicit opt-out path and is also the automatic fallback when the one-password open cannot complete. | Sink flag | `skip_chrome_sqlite` | CDP | `delivery` marker | Keychain open attempted | |---|---|---|---|---| | (none) | `false` | `false` | `universal` | yes; on failure downgrades to degraded non-fatally | | `--write-chrome-sqlite` | `false` | `false` | `universal` | yes; on failure WARNS and honors universal intent (no downgrade) | | `--skip-chrome-sqlite` | `true` | `true` (unless `--no-cdp`) | `degraded` | no | | `--skip-keychain-prompt` / `--skip-keychain-access` | `false` | `false` | `universal` | no | In degraded mode the sink daemon never reads Chrome Safe Storage; cookie delivery uses the plaintext sidecar (`~/.agentcookie/cookies-plain.db`) + per-CLI adapter session files + CDP injection into a dedicated `~/.agentcookie/chrome-profile`. The upgrade-to-universal path is one command: `agentcookie wizard set-keychain-access`. ### Supplying the macOS login password non-interactively The universal open prompts for the macOS login password once and never stores it. For headless / CI installs without a TTY, set the environment variable: ```bash AGENTCOOKIE_LOGIN_PASSWORD='…' agentcookie wizard install --as sink \ --peer --code --pair-url http://:9998/pair ``` When neither the env var nor an interactive terminal is available, `acquireLoginPassword` returns `errNoInteractivePassword` and the wizard downgrades to degraded mode non-fatally, prints the upgrade command, and continues to install the LaunchAgent. ## `agentcookie wizard install` flag reference Required. Selects the role. Source generates the code; sink consumes it. Required. The OTHER machine's tailnet hostname. Stored as `peer.hostname` in `source.yaml` / `sink.yaml` and as the filename for `~/.config/agentcookie/keys/.json`. Source pairing listener bind address. Defaults to `:9998`. `0.0.0.0` and other any-interface binds are refused; explicit `127.0.0.1`/`localhost` is allowed for local dev only. Hostname this side announces during pairing. Defaults to `os.Hostname()`. Source-side override for the sink sync URL. Default: `http://:9999/sync`. Sink-side: pairing code from the source's wizard output. Sink-side: source's pairing URL, e.g. `http://:9998/pair`. Force a fresh pairing handshake even if a key already exists for `--peer`. Overwrite existing `source.yaml` / `sink.yaml` / `blocklist.yaml`. Required to change `peer.hostname` in place. Skip installing the LaunchAgent. Configs and pairing only. Do not print the optional `sudo tailscale set --advertise-exit-node` / `--exit-node` hint. Sink: opt OUT of universal delivery. Renders `skip_chrome_sqlite: true`; the sink daemon never reads or writes Chrome's SQLite. Overrides `--write-chrome-sqlite` when both are passed. Sink: force universal delivery and honor it even if the one-password keychain open cannot complete (does not silently downgrade). Sink: in degraded mode, do not enable CDP injection. Sidecar + adapter remain the cookie-delivery paths. Sink: do not trigger the Chrome Safe Storage Keychain step during install. The sink daemon prompts on first sync instead. Sink: do not expand the Safe Storage partition list. Apple-tool callers may then prompt on first read. Sink: do not run the legacy v0.10 set-keychain-access strategies (the kooky-CGO probe + partition/trust-list loop). Sink: suppress the post-install cookie-bridge env-var hint. `agentcookie wizard uninstall --as ` removes the LaunchAgent. Add `--purge` to also delete configs and paired keys. ## What `wizard install` writes ```text ~/.config/agentcookie/ source.yaml (source side; sink URL + Chrome DB path + peer hostname) sink.yaml (sink side; listen addr + peer hostname + delivery + cdp) blocklist.yaml (both sides; SQLite LIKE patterns, all commented by default) keys/.json (per-peer X25519/HKDF-derived AES-256-GCM key) ~/.agentcookie/ pairing.json (source side, removed once pairing completes) logs/ (LaunchAgent stdout/stderr) cookies-plain.db (sink side, plaintext sidecar; mode 0600) secrets// (sink side, secrets bus per CLI; mode 0600) chrome-profile/ (sink side, CDP-managed Chrome profile in degraded mode) ~/Library/LaunchAgents/ dev.agentcookie.source.plist (source; `agentcookie source --watch`) dev.agentcookie.sink.plist (sink; `agentcookie sink`) ``` The installer uses `launchctl bootstrap gui/ `; on an already-loaded label it falls back to `launchctl kickstart -k gui//