agentcookie Documentation

Pages

1. OverviewWhat agentcookie replicates between two Macs, the three cookie delivery surfaces, the parallel secrets bus, and the shortest source-backed path through these docs.
2. InstallationPrerequisites (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.
3. QuickstartFive-minute laptop + second-Mac pairing: drop configs, run `agentcookie pair`, start the sink LaunchAgent, push from source, and verify with `agentcookie status`.
4. Headless second-Mac installSSH-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.
5. Source and sink topologyThe one-way laptop-to-second-Mac model: the source watcher, the sink listener, the role split, and what each side reads and writes.
6. Cookie delivery surfacesThe 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.
7. Secrets busHow bearer tokens, API keys, and KEY=VALUE auth blobs ride the same encrypted push, land at `~/.agentcookie/secrets/<cli>/secrets.env`, and the v2 adoption tiers (explicit manifest, PP-CLI auto, legacy v1).
8. Pairing and per-peer keysX25519 + HKDF-SHA256 handshake, the base32 pairing code, the per-peer key file at `~/.config/agentcookie/keys/<peer>.json`, rate-limiting on `/pair`, and the sealed master key.
9. Device-bound cookies (DBSC)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 sinkEditing `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 deliveryThe 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.tomlAuthoring 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 adapterThe ~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 agentUsing 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 referenceEvery `agentcookie` subcommand and its flags: `source`, `sink`, `pair`, `wizard`, `doctor`, `status`, `secret`, `discover`, `cookies`, `version`.
16. Configuration files referenceSchemas 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 referenceThe v2 adoption manifest schema: `schema_version`, `[secrets]`, `[aliases]`, `[[files]]`, project kinds, discovery roots, and the three integration tiers.
18. Wire protocol v1HTTP-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 layoutThe v1 standard layout under `~/.agentcookie/secrets/<cli>/`, file modes (0600), `secrets.env` format, optional sealed twin, and the `[[files]]` materialization path.
20. pkg/agentcookiesecret reader libraryIn-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 verificationThe fifteen `agentcookie doctor` check categories, the `DoctorReport` JSON envelope, `wizard verify-adapters` output, and exit-code semantics for agent consumption.
22. LaunchAgent managementHow `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 notarizationThe goreleaser pipeline, the `sign.sh` / `notarize.sh` / `release-tarball.sh` scripts, Developer ID signing for `teamid:` partition trust, and CI secret renewal.
24. TroubleshootingCommon failures and recovery: pairing `connection refused`, sink Keychain prompts, missing `~/go/bin` on the sink, stale Chrome `SingletonLock`, DBSC-suspect drops, and the FAQ.