AuthoCookie

AuthoCookie is a small Playwright sidecar that preserves routine Gemini Web session cookie rotation without adding browser automation to your inference service.

It starts one long-lived headless Chromium process, loads an existing cookie string, visits Gemini periodically, reads the live browser cookie jar, and saves only the authentication cookies that Gemini routinely rotates.

What it saves

AuthoCookie updates only these cookie values:

• __Secure-1PSID
• __Secure-1PSIDTS
• __Secure-1PSIDCC

Unrelated analytics, consent, and short-lived browser cookies are ignored. Existing cookie order and unrelated values are preserved.

Features

• Runs separately from your API or inference bridge
• Keeps one Chromium process alive instead of launching one per request
• Refreshes immediately at startup and every five minutes by default
• Detects manual changes to the cookie file and reloads them automatically
• Replaces the cookie file atomically with mode 0600
• Publishes no network ports
• Includes no login flow and stores no account password

Requirements

• Docker with Compose support
• An existing authenticated Gemini Web cookie string
• About 500 MB of available memory for headless Chromium

Quick start

Create the session directory and add your exported Cookie header value:

mkdir -p session
chmod 700 session
printf '%s\n' 'YOUR_COOKIE_HEADER_VALUE' > session/cookie.txt
chmod 600 session/cookie.txt

Do not paste real credentials into Compose files, shell history, source code, or Git.

Start the keeper from source:

docker compose up -d --build

A prebuilt linux/amd64 image is also published to GHCR:

docker pull ghcr.io/sortedcord/authocookie:latest

To use it with Compose, replace build: . with:

image: ghcr.io/sortedcord/authocookie:latest

Follow its logs:

docker compose logs -f authocookie

A successful rotation produces a message like:

[cookie-keeper] persisted rotated Gemini session cookies

Compose configuration

The included compose.yaml mounts the entire session directory. This is required because AuthoCookie replaces cookie.txt atomically. A single-file bind mount can remain attached to the old inode after replacement.

services:
  authocookie:
    build: .
    restart: unless-stopped
    init: true
    shm_size: "512mb"
    environment:
      COOKIE_FILE: /session/cookie.txt
      REFRESH_INTERVAL_MS: "300000"
      PAGE_SETTLE_MS: "5000"
    volumes:
      - ./session:/session

If another container consumes the cookie, mount the same directory read-only:

services:
  gemini-bridge:
    volumes:
      - ./session:/session:ro

Configure that service to read /session/cookie.txt. Services that cache credentials should watch the file modification time or reload the file for each new session.

Environment variables

• COOKIE_FILE: defaults to /session/cookie.txt. This is the cookie string file shared with the consumer.
• REFRESH_INTERVAL_MS: defaults to 300000. The minimum accepted value is 60000 ms.
• PAGE_SETTLE_MS: defaults to 5000. This allows browser cookie updates to finish after Gemini loads.
• BROWSER_USER_AGENT: optionally overrides the Chromium-like Linux user agent.

Updating credentials

If Google requires a new login, replace the file atomically on the host:

install -m 600 new-cookie.txt session/.cookie.new
mv -f session/.cookie.new session/cookie.txt

AuthoCookie notices the changed content on its next cycle. Restarting the container triggers an immediate cycle:

docker compose restart authocookie

Security

The cookie file grants access to an authenticated Google browser session. Treat it like an API key.

• Never commit cookie files
• Keep the session directory at mode 0700
• Keep the cookie file at mode 0600
• Do not publish the session directory over network storage
• Prefer a dedicated Google account for automation
• Do not expose Chromium or debugging ports

The provided .gitignore excludes common credential filenames and session directories. Always inspect git diff --cached before publishing.

Limitations

AuthoCookie preserves routine cookie rotation. It cannot recover from a full logout, revoked account session, password reset, MFA prompt, CAPTCHA, or Google security challenge. Those cases require a fresh authenticated cookie export.

Google can change Gemini Web behavior without notice because this uses an undocumented browser session flow.

Development

Run the unit tests:

npm test

Build the container:

docker build -t authocookie .

Attribution

The selective Gemini cookie merge behavior is based on the approach used by OmniRoute. AuthoCookie keeps that browser work outside the inference path.