Skip to main content
Cookie import allows you to inject cookies from your real browser into Camofox sessions, skipping interactive login flows. This is essential for accessing sites that require authentication.
Cookie import is disabled by default. You must set CAMOFOX_API_KEY to enable this endpoint for security reasons.

​
Security model

Cookie injection moves Camofox from “anonymous browsing” to “authenticated browsing.” Because cookies are sensitive credentials, the import endpoint requires API key authentication:
  • Disabled by default: If CAMOFOX_API_KEY is not set, all cookie import requests return 403 Forbidden
  • Bearer token authentication: Requests must include Authorization: Bearer <CAMOFOX_API_KEY> header
  • Timing-safe comparison: The server uses constant-time comparison to prevent timing attacks
  • Field sanitization: Only allowed Playwright cookie fields are accepted (name, value, domain, path, expires, httpOnly, secure, sameSite)
  • Size limits: Maximum 500 cookies per request, 5MB file size limit
  • Path traversal protection: Cookie file paths are resolved relative to CAMOFOX_COOKIES_DIR and cannot escape that directory

​
Setup workflow

1

Generate a secret API key

Generate a cryptographically secure random key:
# macOS / Linux
openssl rand -hex 32
This produces a 64-character hex string like:
a1b2c3d4e5f6...
2

Set the environment variable

The same key is used by both the OpenClaw plugin (to authenticate requests) and the Camofox server (to verify them). Since both run from the same environment, set it once:
export CAMOFOX_API_KEY="your-generated-key"
openclaw start
Why an environment variable? Plugin config in openclaw.json is stored in plaintext, so secrets don’t belong there. Set CAMOFOX_API_KEY in your shell profile, systemd unit, Docker env, or Fly.io secrets.
For Docker deployment:
docker run -p 9377:9377 \
  -e CAMOFOX_API_KEY="your-generated-key" \
  camofox-browser
For Fly.io:
fly secrets set CAMOFOX_API_KEY="your-generated-key"
3

Export cookies from your browser

Install a browser extension that exports Netscape-format cookie files:
  1. Navigate to the site you want to authenticate (e.g., linkedin.com)
  2. Click the extension icon
  3. Export cookies for the current site
  4. Save the file (e.g., linkedin_cookies.txt)
4

Place the cookie file

Copy the exported file to Camofox’s cookie directory:
mkdir -p ~/.camofox/cookies
cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt
The default directory is ~/.camofox/cookies/. Override with the CAMOFOX_COOKIES_DIR environment variable.
For Docker deployments, mount the cookies directory as a read-only volume:
docker run -p 9377:9377 \
  -e CAMOFOX_API_KEY="your-key" \
  -v ~/.camofox/cookies:/root/.camofox/cookies:ro \
  camofox-browser
5

Import cookies into your session

​
Using the OpenClaw plugin

Ask your agent to import cookies:
Import my LinkedIn cookies from linkedin.txt
The agent calls camofox_import_cookies → reads the file → POSTs to the server with the Bearer token → cookies are injected into the browser session.

​
Using the standalone API

Read and parse the cookie file, then POST to the session endpoint:
curl -X POST http://localhost:9377/sessions/agent1/cookies \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
  -d '{
    "cookies": [
      {
        "name": "li_at",
        "value": "AQEDATEABCDEFabcdef123456",
        "domain": ".linkedin.com",
        "path": "/",
        "expires": 1735689600,
        "httpOnly": true,
        "secure": true
      }
    ]
  }'
Cookies must be in Playwright’s cookie object format. Use the lib/cookies.js module’s parseNetscapeCookieFile() function to convert Netscape format to Playwright format.
6

Verify authentication

Subsequent camofox_create_tab or /tabs requests to the authenticated domain will use the imported cookies:
POST /tabs
{
  "userId": "agent1",
  "sessionKey": "task1",
  "url": "https://www.linkedin.com/feed/"
}
The page loads with your authenticated session.

​
How it works

The cookie import flow isolates file I/O, parsing, and network operations: 
~/.camofox/cookies/linkedin.txt          (Netscape format, on disk)
        │
        ▼
camofox_import_cookies tool              (parses file, filters by domain)
        │
        ▼  POST /sessions/:userId/cookies
        │  Authorization: Bearer <CAMOFOX_API_KEY>
        │  Body: { cookies: [Playwright cookie objects] }
        ▼
camofox server                           (validates, sanitizes, injects)
        │
        ▼  context.addCookies(...)
        │
Camoufox browser session                 (authenticated browsing)

​
File parsing

The lib/cookies.js module parses Netscape-format cookie files: 
# Netscape HTTP Cookie File
.linkedin.com	TRUE	/	TRUE	1735689600	li_at	AQEDATEABCDEF...
Supports #HttpOnly_ prefix for HttpOnly cookies. The parser:
  1. Strips UTF-8 BOM if present
  2. Skips comments (lines starting with # except #HttpOnly_)
  3. Parses tab-separated fields: domain, flag, path, secure, expires, name, value
  4. Converts to Playwright cookie objects with required fields

​
Server validation

The server endpoint (server.js:102-168) validates:
  • API key: Bearer token must match CAMOFOX_API_KEY using timing-safe comparison
  • Request structure: cookies field must be an array
  • Cookie count: Maximum 500 cookies per request
  • Cookie objects: Each must have name, value, and domain fields
  • Field allowlist: Only name, value, domain, path, expires, httpOnly, secure, sameSite are preserved
Invalid requests return 400 Bad Request with details.

​
API reference

​
POST /sessions/:userId/cookies

Inject cookies into a user’s browser context. Headers: 
Authorization: Bearer YOUR_CAMOFOX_API_KEY
Content-Type: application/json
Body: 
{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": "example.com",
      "path": "/",
      "expires": -1,
      "httpOnly": false,
      "secure": false,
      "sameSite": "Lax"
    }
  ]
}
Response (200 OK): 
{
  "ok": true,
  "userId": "agent1",
  "count": 1
}
Response (403 Forbidden): 
{
  "error": "Cookie import is disabled. Set CAMOFOX_API_KEY to enable this endpoint."
}

​
Environment variables

VariableDescriptionDefault
CAMOFOX_API_KEYAPI key for cookie import (disabled if unset)-
CAMOFOX_COOKIES_DIRDirectory for cookie files~/.camofox/cookies

​
Common issues

​
403 Forbidden

Cause: CAMOFOX_API_KEY is not set or the Bearer token is incorrect. Fix: Set the environment variable before starting the server: 
export CAMOFOX_API_KEY="your-key"
npm start

​
Cookies not applied

Cause: Cookie domain mismatch or expired cookies. Fix: Ensure the cookie domain matches the site you’re visiting. LinkedIn cookies typically use .linkedin.com (note the leading dot for subdomain matching).

​
Path traversal error

Cause: Attempting to read a file outside CAMOFOX_COOKIES_DIR. Fix: Cookie file paths must be relative paths within the cookies directory. No ../ or absolute paths allowed.

Build docs developers (and LLMs) love

Get started for freeTalk to us