# 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.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/mvanhorn-agentcookie-137da38edfae)
- [GitHub repository](https://github.com/mvanhorn/agentcookie)

## Repository

- Repository: mvanhorn/agentcookie

- Generated: 2026-06-01T03:16:41.694Z
- Updated: 2026-06-01T03:20:26.881Z
- Runtime: Claude Code
- Format: Documentation
- Pages: 24

## Pages

- [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.
- [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.
- [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`.
- [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.
- [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.
- [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.
- [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/<cli>/secrets.env`, and the v2 adoption tiers (explicit manifest, PP-CLI auto, legacy v1).
- [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/<peer>.json`, rate-limiting on `/pair`, and the sealed master key.
- [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.
- [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.
- [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.
- [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.
- [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.
- [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.
- [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`.
- [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).
- [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.
- [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).
- [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/<cli>/`, file modes (0600), `secrets.env` format, optional sealed twin, and the `[[files]]` materialization path.
- [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.
- [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.
- [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.
- [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.
- [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 Files

- `.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`