How to Import Netscape-Format Cookie Files in Camofox-Browser for Authenticated Sessions

To import Netscape-format cookies in camofox-browser, place your cookies.txt file in the configured cookies directory and invoke the camofox_import_cookies tool, which parses the file via parseNetscapeCookieFile in lib/cookies.js and injects the cookies into the Playwright context through the POST /sessions/:userId/cookies endpoint.

The jo-inc/camofox-browser repository provides a specialized pipeline for converting classic Netscape-style cookie files into authenticated Playwright browser sessions. This functionality enables automated access to protected websites like LinkedIn or Google without manual login flows. Understanding how to properly import Netscape-format cookie files is essential for maintaining persistent authenticated states across browser automation tasks.

Understanding the Cookie Import Architecture

The import system consists of three integrated components that transform raw text files into active browser cookies.

Cookie Parser (lib/cookies.js): Handles the parseNetscapeCookieFile and readCookieFile functions that normalize Netscape format lines into structured objects. It supports the #HttpOnly_ prefix and extracts fields including name, value, domain, path, expires, httpOnly, and secure.

OpenClaw Tool (plugin.ts): Exposes the camofox_import_cookies function to agent scripts. This tool resolves file paths relative to CAMOFOX_COOKIES_DIR, optionally filters by domain suffix, and forwards parsed cookies to the server endpoint.

Server Endpoint (server.js): Receives validated cookie arrays at POST /sessions/:userId/cookies, sanitizes input against field whitelists, and executes session.context.addCookies() to inject them into the active Playwright context.

Step-by-Step Import Process

When you initiate a cookie import, the system executes the following validation and injection pipeline:

1. Path Resolution: The system resolves the provided cookiesPath relative to CAMOFOX_COOKIES_DIR (default: ~/.camofox/cookies). The resolver in lib/config.js ensures the final path starts with the base directory to prevent directory-traversal attacks.

2. Size Validation: Files exceeding 5 MiB are automatically rejected to prevent memory exhaustion attacks.

3. Netscape Parsing: The parseNetscapeCookieFile function splits the file line-by-line, handling tab-separated values and the #HttpOnly_ prefix for secure cookies.

4. Domain Filtering: If a domainSuffix parameter is provided, only cookies whose domain ends with that suffix are retained (e.g., .linkedin.com).

5. Authorization: Requests require a valid CAMOFOX_API_KEY header; local development bypasses this for loopback requests (127.0.0.1).

6. Server Validation: The endpoint verifies the JSON body contains a cookies array with maximum 500 entries, each containing required fields (name, value, domain) and optional allowed fields (path, expires, httpOnly, secure, sameSite).

7. Context Injection: Validated cookies are passed to Playwright's addCookies() method, making them immediately available for all subsequent navigation calls.

Implementation Methods

You can import cookies using either the provided OpenClaw tool or direct HTTP API calls.

Using the OpenClaw Tool from Agent Scripts

The recommended approach uses the registered tool in your automation scripts:

// Tool invocation within OpenClaw runtime
await api.runTool('camofox_import_cookies', {
  cookiesPath: 'linkedin_cookies.txt',      // Relative to CAMOFOX_COOKIES_DIR
  domainSuffix: '.linkedin.com',           // Optional: filter specific domains
});

This method automatically handles path resolution, parsing, and the HTTP POST to the server endpoint. The tool reads from ~/.camofox/cookies/linkedin_cookies.txt, converts Netscape lines to objects, and sends them to /sessions/<userId>/cookies with proper authentication headers.

Direct HTTP API Calls

For external scripts or manual testing, use curl to POST pre-parsed JSON:

# Set required authentication

export CAMOFOX_API_KEY=super-secret-key

# Post cookie data directly

curl -X POST http://localhost:9377/sessions/me/cookies \
  -H "Authorization: Bearer $CAMOFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @cookies.json

The cookies.json file must contain a valid array structure:

[
  {
    "name": "li_at",
    "value": "AQEDASDF...",
    "domain": ".linkedin.com",
    "path": "/",
    "expires": 1700000000,
    "httpOnly": true,
    "secure": true
  }
]

Netscape File Format Requirements

Camofox-browser expects standard Netscape cookie file format with tab-separated values. Each line represents one cookie with the following structure:

domain  flag  path  secure  expiration  name  value

Example valid file contents:

#HttpOnly_.linkedin.com	TRUE	/	TRUE	1700000000	li_at	ABCD1234
.example.com	TRUE	/	FALSE	0	sessionid	xyz

The parser automatically strips the #HttpOnly_ prefix and sets the httpOnly boolean accordingly. Boolean fields (TRUE/FALSE) are normalized to JavaScript boolean values during conversion.

Configuration and Security Considerations

Environment Variables

Configure these variables in lib/config.js before importing:

Variable	Purpose	Default
CAMOFOX_COOKIES_DIR	Base directory for relative cookie paths	~/.camofox/cookies
CAMOFOX_API_KEY	Authentication token for production imports	none
CAMOFOX_PORT	HTTP server port	9377

Security Safeguards

The implementation includes multiple protection layers:

• Path Confinement: The readCookieFile function rejects any path that resolves outside CAMOFOX_COOKIES_DIR using path.resolve() validation.

• Input Limits: Maximum file size of 5 MiB and maximum 500 cookies per request prevent resource exhaustion.

• Field Whitelisting: The server endpoint in server.js (lines 166-227) strips unknown fields before passing data to Playwright, mitigating prototype pollution attacks.

• Authentication: Production environments require CAMOFOX_API_KEY; only loopback interfaces bypass authentication for local development.

Summary

• Place Netscape-format cookies.txt files in CAMOFOX_COOKIES_DIR (default ~/.camofox/cookies) before importing.
• Use the camofox_import_cookies tool for automated resolution and injection, or POST directly to /sessions/:userId/cookies with a valid API key.
• The parser supports standard Netscape format including #HttpOnly_ prefixes and extracts seven standard cookie fields.
• Security controls include path traversal prevention, 5 MiB size limits, 500-cookie caps, and strict field whitelisting.
• Configuration is centralized in lib/config.js and consumed by both the server and OpenClaw tool registration in plugin.ts.

Frequently Asked Questions

What is the maximum number of cookies I can import at once?

Camofox-browser enforces a limit of 500 cookies per import request. The server endpoint in server.js validates the array length and rejects requests exceeding this threshold. If your cookie file contains more entries, split them into multiple import calls or trim unnecessary entries before importing.

Can I import cookies from any directory on my system?

No. For security reasons, the readCookieFile function in lib/cookies.js resolves all paths relative to CAMOFOX_COOKIES_DIR (default ~/.camofox/cookies). The resolver checks that the final absolute path starts with the base directory, rejecting attempts to traverse to parent directories using ../ patterns or absolute system paths outside the designated folder.

Does camofox-browser support cookie formats other than Netscape?

The current implementation specifically targets Netscape-format cookies.txt files through the parseNetscapeCookieFile function. While the server endpoint accepts standard JSON cookie arrays (allowing custom scripting conversions), the built-in tool chain only processes Netscape tab-separated format. To use other formats, convert them to the expected JSON structure and POST directly to the /sessions/:userId/cookies endpoint.

How do I verify that cookies were successfully injected?

After calling camofox_import_cookies or posting to the endpoint, navigate to a protected page requiring authentication. The session.context.addCookies() method in server.js immediately makes cookies available to the Playwright context, so subsequent navigation calls should reflect the authenticated state. Check for the absence of login redirects or the presence of session-specific UI elements to confirm successful injection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}