DOCSEARCHbyAlgolia
Submit Docs

agentcookie

repository·main·Indexed 20 days ago

https://github.com/mvanhorn/agentcookie

A session-synchronization tool for agentic workflows that replicates Chrome cookies and per-CLI secrets (API keys, bearer tokens) from a primary machine to a secondary agent machine over a Tailscale tailnet. It allows headless agents to act as the authenticated user via a secrets bus, supporting custom manifests for CLI adaptation, a gh-shim for GitHub CLI, and integration with the cmux WebKit browser.

Tokens
82.7K
Snippets
216
Records
352
Agent score
70%

What's inside agentcookie

  1. Configure secret aliases in agentcookie.toml

    main

    Use the [aliases] table to map your internal bus keys to the environment variable names expected by your CLI tools. This allows a CLI that expects TESLA_AUTH_TOKEN to automatically receive a value that was originally stored under a different key like OAUTH_BEARER.

    Rules:

    • The key (consumer variable) and value (bus key) must both be valid environment variable names.
    • If a user manually runs agentcookie secret alias <name> <key> on their local machine, the local alias overrides this manifest alias.
    • If the bus key specified in the alias is missing, the alias becomes a no-op.
    [aliases]
TESLA_AUTH_TOKEN = "OAUTH_BEARER"

  2. Understand the risks and constraints of universal cookie delivery

    main

    When using universal cookie delivery, be aware of the following operational constraints and safety invariants:

    Safety Invariants

    • Cookie-safety invariant: The system follows a "refuse-rather-than-rewrite" policy. It will never rewrite a Safe Storage value to prevent catastrophic cookie-wiping. If a value cannot be safely updated, the system captures a rollback artifact first.

    Operational Risks

    • Degraded Mode (Headless/No GUI): On headless boxes without a GUI session or a password, the system is designed to land in a "degraded" state via the upgrade command. This is expected behavior for non-interactive environments.
    • Unsigned Binaries: The daemon binary must be Dev-ID signed (e.g., for teamid: coverage). The installation process will issue a warning if an unsigned binary is detected.
    • Keychain Re-lock: Using SSH keychain re-lock can sometimes mask partition failures behind expected verification failures. The system mitigates this by making verification advisory and gating delivery on successful partition-set status.
    • Daemon/Chrome Quiescence: During certain setup phases, the daemon or Chrome may be temporarily unavailable. The system is designed to restore the daemon automatically upon error.

  3. How agentcookie and tesla-pp-cli integrate for automatic Tesla control

    main

    The integration between agentcookie and tesla-pp-cli (from the Printing Press library) is designed to provide zero-ceremony Tesla vehicle control on a sink machine.

    Instead of manual environment variable aliasing, the system uses a sealed file-carriage mechanism. The agentcookie bus carries the Tesla config.toml (and optionally a signing key) as a sealed file to the sink. The sink machine then materializes these as 0600 permission files under ~/.agentcookie/ and reads them directly. This approach avoids the 'stale bearer' problem by allowing the sink to refresh its own tokens using the synced refresh material, ensuring the OAUTH_BEARER remains valid without constant re-syncing from the source.

  4. Understand sync-safety classifications for secrets

    main

    When designing or using the secrets-bus to replicate credentials, data is categorized into three sync-safety classes. This determines whether a secret can be moved from a source machine to a sink (agent) machine:

    1. safe-to-sync: Data that represents a user identity regardless of the machine. Sharing these bytes does not break the authentication flow.
      • Examples: OAuth access/refresh tokens, API keys, session cookies, and vendor partner-app credentials (e.g., client_id, client_secret).
    2. local-only: Data that must never leave the device that generated it. These are often used as proof of a specific device's identity. Replicating them allows another machine to impersonate the original host.
      • Examples: ECDSA/RSA private signing keys (e.g., Tesla snowflake-private.pem), per-machine integrity values (e.g., SF360_HOST_FINGERPRINT), and macOS Keychain items pinned to specific binaries.
    3. device-bound-but-shippable: Data that certifies a specific device but is acceptable to sync to a trusted secondary machine (the agent sink).
      • Examples: Browser session proofs (eBay, OpenArt, Suno), Superhuman deviceId, and Slack system_id.

  5. Handle edge cases when authoring agentcookie manifests

    main

    When designing your manifest, consider these constraints and workarounds:

    • macOS Keychain: The [secrets.keychain] support is reserved for v2.1. Currently, export keychain entries to a stable .env file and point the manifest at that file.
    • Short-lived JWTs: The bus is designed for stable tokens (API keys, refresh tokens). Do not ship per-session JWTs. Instead, ship the stable refresh token or the OAuth client_id and client_secret.
    • Multiple Secret Files: A manifest can only point to one [secrets.file]. Either consolidate secrets into one file or ship multiple manifests with different name slugs (e.g., my-tool-auth and my-tool-config).
    • File-shaped Secrets (PEMs, certs): The bus only carries env-shaped key-value pairs. Keep file-shaped artifacts (like signing keys) local and only ship the associated bearer tokens via the bus.
    • Multi-account Support: The bus is single-account. To support multiple environments (e.g., dev vs prod), use distinct slugs for each (e.g., my-tool-dev and my-tool-prod) and ship separate manifests.

    Important Restrictions

    • DO NOT import pkg/agentcookiesecret into your tool unless you want your tool to read from the bus directly. The bus is intended to deliver secrets to your tool's existing file location.
    • DO NOT put real secrets in the manifest. The manifest is a pointer to the secret location, not the secret itself.
    • DO NOT sign the manifest (v2.0 ignores signed_by).
    • DO NOT ship manifests from untrusted sources (like public CDNs) as the [secrets.file].path is a potential path-traversal vector.

  6. Compare agentcookie v1 and v2 adoption standards

    main

    Understanding the difference between v1 and v2 is critical for migration and implementation. v1 defines the wire format (how data is actually moved), while v2 defines the adoption standard (how projects declare their secrets to the system).

    Concernv1 (wire format)v2 (adoption standard)
    File location~/.agentcookie/secrets/<name>/secrets.env~/.agentcookie/manifests/<name>.toml (declarations); secrets read from wherever the manifest points
    FormatKEY=VALUE dotenvTOML manifest pointing at KEY=VALUE dotenv
    Adoption flowagentcookie secret import-from (imperative, user-driven)Project drops manifest, agentcookie auto-discovers (declarative, author-driven)
    Source of truthThe bus directoryThe project's own file (read-in-place)
    Wire envelopeenvelope.Secrets map[string]map[string]stringSame
    Sink behaviorWrite per-CLI bus directorySame
    Default behaviorEmpty bus; user addsEmpty registry; user installs manifest-shipping projects

    Note: v2 is the new recommended default. Both are available in agentcookie v0.14.0-beta.1 and later.

  7. Understand the agentcookie secrets bus concept

    main

    The secrets bus is a feature designed to synchronize CLI authentication tokens (API keys, OAuth tokens, etc.) from a laptop to a sink machine, mirroring how agentcookie synchronizes browser cookies.

    Instead of manually copying files or re-authenticating on every machine, agentcookie watches for changes in a local secrets directory, encrypts the payload using AES-256-GCM, and ships it to the sink. On the sink, the secrets are unsealed and written as standard .env files in predictable locations. This allows any CLI (whether part of the Printing Press ecosystem or a third-party tool like gh or aws) to opt-in by simply reading these .env files using a standard dotenv parser.

  8. The agentcookie secrets bus data contract

    main

    The agentcookie secrets bus writes one file per CLI at: ~/.agentcookie/secrets/<your-cli-name>/secrets.env

    Format Details:

    • Content: Plain KEY=VALUE lines, one per line.
    • Permissions: Mode 0600.
    • Encryption: When a v0.12 master key is configured, a sealed version secrets.env.sealed is created. The plaintext secrets.env may be absent if the system is configured to only use sealed files.
    • Grammar: See docs/spec-agentcookie-secrets-bus-v1.md for full lookup priority and grammar details.

  9. Understand the agentcookie secrets bus priority chain

    main

    When a reference reader resolves secrets for a specific CLI name, it populates a string-to-string map using a specific priority chain. Later steps fill in keys that earlier steps did not provide, but they never overwrite keys already provided by a higher-priority source.

    Priority Order (Highest to Lowest):

    1. Sealed file: ~/.agentcookie/secrets/<cli-name>/secrets.env.sealed. This is the authoritative dataset when sealing is enabled.
    2. Plaintext file: ~/.agentcookie/secrets/<cli-name>/secrets.env. The fallback dataset if no sealed file is present.
    3. Caller-registered fallback file: An optional secondary config file (e.g., a CLI's own config.toml) provided by the reader. The reader may use heuristics to map these to expected keys.
    4. Process environment: Environment variables matching expected key names. This is the source of last resort to ensure backward compatibility.

    Crucial Rule: Bus over Env The bus (Sealed/Plaintext files) MUST have higher priority than environment variables. This ensures that if a user has a leftover environment variable from an old workflow, the bus remains the authoritative source and is not silently ignored.

    # Priority Chain Summary
1. ~/.agentcookie/secrets/<cli-name>/secrets.env.sealed (Sealed)
2. ~/.agentcookie/secrets/<cli-name>/secrets.env (Plaintext)
3. User-provided fallback file (e.g., ~/.config/<cli-name>/config.toml)
4. Process Environment Variables

  10. Sync and materialize sealed multiline/file secrets

    main

    The agentcookie secrets bus supports carrying sealed multiline secrets (such as EC PEM files). When a secret is declared as a file item in the manifest, the sink will materialize it as a local file with 0600 permissions inside the ~/.agentcookie/ directory.

    This mechanism ensures that sensitive keys, like those required for TESLA_FLEET_KEY_FILE, are delivered securely and are not world-readable. Note that file materialization is an opt-in process for specific signing-key items.

  11. Handling identity collisions in manifests

    main

    When multiple manifests declare the same secret name, agentcookie handles collisions based on how the name was defined:

    1. Explicit Collisions: If two different agentcookie.toml files both explicitly declare the same name, this results in a hard error. This prevents accidental or malicious overwriting of named secrets.
    2. Derived Collisions: If a name derived automatically by a Printing Press (PP) CLI conflicts with an explicitly defined name in an agentcookie.toml file, the explicit manifest wins. The derived name is automatically suffixed with -pp (e.g., <name>-pp) and the collision is logged.

  12. The agentcookie adoption standard

    main

    The project uses an adoption standard to manage how different agents integrate with the sync engine. There are three integration tiers:

    1. explicit-manifest: Using an agentcookie.toml manifest.
    2. pp-cli-derived: Derived from the CLI's own configuration.
    3. legacy-v1: Support for the older version 1 format.

    Users can use agentcookie discover to identify which tier their current environment falls into.