Cookie Management

Inject, persist, and restore cookies for pre-authenticated sessions and repeatable browser state.

Prerequisites

BotBrowser binary installed. See INSTALLATION.md.
A profile file (.enc or .json).
PRO license for the --bot-cookies flag.

Overview

The --bot-cookies flag lets you inject cookies into BotBrowser sessions at launch time. Cookies are loaded before the first page navigation, so the browser starts with the desired session state. This is useful for restoring authenticated sessions, setting consent preferences, or pre-populating any cookie-dependent state.

With Per-Context Fingerprint, --bot-cookies can also be passed when creating a BrowserContext. This lets each context start with its own cookie state while sharing one browser process.

You can provide cookies as inline JSON directly in the flag value, or load them from a JSON file.

Quick Start

Inline JSON


chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --bot-cookies='[{"url":"https://example.com","name":"session_id","value":"abc123","domain":".example.com"}]'

From a file


chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --bot-cookies="@path/to/cookies.json"

The file should contain a JSON array of cookie objects.

How It Works

Cookie parsing. At launch, BotBrowser reads the --bot-cookies value. If it starts with @, the remainder is treated as a file path. Otherwise, the value is parsed as inline JSON.
Cookie injection. Cookies are injected into the browser’s cookie store before any page navigation occurs. This means the first HTTP request already includes the injected cookies.
Domain matching. Each cookie must include a url field. The browser uses it to set the cookie origin and only sends cookies to matching domains, following standard cookie rules.
Per-context import. When --bot-cookies is passed through botbrowserFlags at BrowserContext creation time, cookies are imported into that context only.

Each cookie object supports these fields:

Field	Required	Description
`url`	Yes	Full URL used to set the cookie (e.g., `https://example.com`). Required for the cookie to be accepted.
`name`	Yes	Cookie name.
`value`	Yes	Cookie value.
`domain`	No	Domain the cookie belongs to. Prefix with `.` for subdomains (e.g., `.example.com`).
`path`	No	Cookie path. Defaults to `/`.
`secure`	No	Whether the cookie requires HTTPS. Defaults to `true`.
`httpOnly`	No	Whether the cookie is HTTP-only (not accessible via JavaScript). Defaults to `false`.
`sameSite`	No	SameSite attribute: `strict`, `lax`, or `none`.
`expirationDate`	No	Expiration time as a Unix timestamp (seconds since epoch).

Common Scenarios

Pre-authenticated session (Playwright)


import { chromium } from "playwright-core";
 
const cookies = JSON.stringify([
  {
    url: "https://example.com",
    name: "session_id",
    value: "abc123def456",
    domain: ".example.com",
    path: "/",
    secure: true,
    httpOnly: true,
  },
  {
    url: "https://example.com",
    name: "user_prefs",
    value: "theme=dark",
    domain: ".example.com",
    path: "/",
  },
]);
 
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    "--bot-profile=path/to/profile.enc",
    `--bot-cookies=${cookies}`,
  ],
});
 
const page = await browser.newPage();
await page.goto("https://example.com/dashboard"); // Loads as authenticated user
await browser.close();

Pre-authenticated session (Puppeteer)

With Puppeteer, use browser.defaultBrowserContext() to access the context that --bot-cookies injects into. context.cookies() returns all cookies for the context without a URL argument.


import puppeteer from "puppeteer-core";
 
const cookies = JSON.stringify([
  {
    url: "https://example.com",
    name: "session_id",
    value: "abc123def456",
    domain: ".example.com",
    path: "/",
    secure: true,
    httpOnly: true,
  },
]);
 
const browser = await puppeteer.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    "--bot-profile=path/to/profile.enc",
    `--bot-cookies=${cookies}`,
  ],
});
 
const context = browser.defaultBrowserContext();
const page = await context.newPage();
await page.goto("https://example.com/dashboard");
 
const injectedCookies = await context.cookies();
console.log(injectedCookies);
 
await browser.close();


const consentCookies = JSON.stringify([
  {
    url: "https://example.com",
    name: "cookie_consent",
    value: "accepted",
    domain: ".example.com",
    path: "/",
    expirationDate: Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60,
  },
]);
 
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    "--bot-profile=path/to/profile.enc",
    `--bot-cookies=${consentCookies}`,
  ],
});

Loading cookies from a file

Create a cookies.json file:


[
  {
    "url": "https://example.com",
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com",
    "path": "/",
    "secure": true,
    "httpOnly": true
  },
  {
    "url": "https://example.com",
    "name": "locale",
    "value": "en-US",
    "domain": ".example.com",
    "path": "/"
  }
]

Then launch with:


chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --bot-cookies="@path/to/cookies.json"

Use --bot-cookies inside botbrowserFlags when each BrowserContext needs its own session state:


const client = await browser.newBrowserCDPSession();
 
const cookies = JSON.stringify([
  {
    url: "https://example.com",
    name: "session_id",
    value: "context-a",
    domain: ".example.com",
    path: "/",
    secure: true,
    httpOnly: true
  }
]);
 
const { browserContextId } = await client.send("Target.createBrowserContext", {
  botbrowserFlags: [
    "--bot-profile=path/to/profile.enc",
    "--bot-cookies=" + cookies
  ]
});

Create pages after the context is created so the first navigation uses the context-scoped cookie state.

JavaScript flag construction

When building the --bot-cookies flag in JavaScript, do not wrap the JSON value in extra quotes:


// Correct
const cookies = [{ url: "https://example.com", name: "sid", value: "abc", domain: ".example.com" }];
args.push("--bot-cookies=" + JSON.stringify(cookies));
 
// Wrong - extra quotes become part of the value
args.push(`--bot-cookies='${JSON.stringify(cookies)}'`);

Troubleshooting / FAQ

Problem	Solution
Cookies not injected (silently skipped)	Each cookie object must include a `url` field (e.g., `"url": "https://example.com"`). Without it, the cookie is silently dropped.
Puppeteer: `context.cookies()` returns empty	For startup cookies, use `browser.defaultBrowserContext()`. For Per-Context Fingerprint, pass `--bot-cookies` through `botbrowserFlags` when creating the BrowserContext.
Cookies not sent with requests	Verify the `domain` field matches the target site. Use `.example.com` (with leading dot) to include subdomains.
”Invalid JSON” error	Check that the cookie value is a valid JSON array. Use a JSON validator if needed.
File not found	When using `@path/to/file.json`, ensure the path is absolute.
Secure cookies not working	Set `secure: true` and access the site via HTTPS.

Next Steps

Bookmark Seeding. Pre-populate bookmarks for session authenticity.
History Seeding. Add browsing history for privacy protection.
CLI Flags Reference. Full flag documentation.
Playwright Guide. Framework integration basics.
Per-Context Fingerprint. Context-scoped profile and session state.

Related documentation: CLI Flags Reference | Profile Configuration

Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.