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

> Easily import Netscape cookie files into Camofox Browser for seamless authenticated sessions. Follow our simple guide to leverage your existing cookies.

- Repository: [jo/camofox-browser](https://github.com/jo-inc/camofox-browser)
- Tags: how-to-guide
- Published: 2026-04-15

---

**To import Netscape-format cookies in camofox-browser, place your [`cookies.txt`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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:

```javascript
// 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:

```bash

# 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`](https://github.com/jo-inc/camofox-browser/blob/main/cookies.json) file must contain a valid array structure:

```json
[
  {
    "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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/lib/config.js) and consumed by both the server and OpenClaw tool registration in [`plugin.ts`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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`](https://github.com/jo-inc/camofox-browser/blob/main/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.