Session Management

Nginjen supports multi-session browser orchestration. Each session runs in its own browser tab with its own fingerprint and optional proxy.

Creating Sessions

Via API

# Create a session with default profile
curl -X POST http://127.0.0.1:9090/sessions \
  -H 'content-type: application/json' \
  -d '{"profile": "windows"}'

# Response
{
  "id": "sess_a1b2c3d4",
  "profile": "windows",
  "created_at": "2026-08-12T10:00:00Z"
}

Session Operations

# Navigate to a URL
curl -X POST http://127.0.0.1:9090/sessions/sess_a1b2c3d4/navigate \
  -H 'content-type: application/json' \
  -d '{"url": "https://example.com"}'

# Execute JavaScript
curl -X POST http://127.0.0.1:9090/sessions/sess_a1b2c3d4/execute \
  -H 'content-type: application/json' \
  -d '{"script": "document.title"}'

# Close session
curl -X DELETE http://127.0.0.1:9090/sessions/sess_a1b2c3d4

Fingerprint Rotation

Each session gets its own FingerprintContext derived from the chosen profile. This means:

• Session A and Session B both using windows profile will have different canvas noise, WebGL renderers (within the valid Windows range), and audio fingerprints
• The OS-level signals (platform, screen size, timezone) will match the profile

Concurrency Control

The server uses a semaphore to limit concurrent browser pages:

[server]
max_concurrent_pages = 5

When the limit is reached, new session requests wait until a slot frees up. This prevents resource exhaustion on low-memory servers.

Cookie Persistence

Cookies are persisted per domain:

# List cookie domains
curl http://127.0.0.1:9090/cookies

# Get cookies for a domain
curl http://127.0.0.1:9090/cookies/example.com

# Save cookies
curl -X POST http://127.0.0.1:9090/cookies/example.com \
  -H 'content-type: application/json' \
  -d '{"cookies": [...]}'

# Delete cookies
curl -X DELETE http://127.0.0.1:9090/cookies/example.com

Cookies survive across server restarts when saved to disk.