🆔 Identity & Profile — Hardware Fingerprint & Browser Settings

Piggy generates a persistent hardware fingerprint and browser profile on first run. This ensures consistent identity across restarts and bypasses fingerprint-based bot detection.

Overview

Two files control Piggy's identity:

File	Purpose	Auto-Generated?	Edit Safely?
`identity.json`	Hardware fingerprint (CPU, RAM, GPU, timezone, noise seeds)	✅ Yes (first run)	❌ No
`profile.json`	Browser settings (UA, headers, GPU strings)	✅ Yes (from identity)	✅ Yes

⚠️ Version Required: Binary v0.1.12+ | Library v0.0.18+

Quick Start

typescript

import piggy from "nothing-browser";

await piggy.connect({
  host: "http://localhost:2005",
  key: "peaseernest..."
});

// Get file paths
const paths = await piggy.sessionPaths();
console.log("Identity:", paths.identity);     // identity.json
console.log("Profile:", paths.profile);       // profile.json

// Hot reload profile after editing
await piggy.sessionReload();

// Check current User-Agent
const currentUA = await piggy.evaluate(() => navigator.userAgent);
console.log("Browser reports:", currentUA);

File Locations

Both files are saved in the same directory as the binary:

/home/user/my-scraper/
├── nothing-browser-headless
├── identity.json          ← DO NOT EDIT (hardware fingerprint)
├── profile.json           ← SAFE TO EDIT (browser settings)
├── cookies.json           ← SAFE TO EDIT
├── ws.json
└── pings.json

`identity.json` — Hardware Fingerprint

Generated On First Run

When you first run the binary, Piggy reads real hardware values from your system:

json

{
  "cpu_cores": 8,
  "ram_gb": 16,
  "screen_resolution": "1920x1080",
  "gpu_vendor": "Intel",
  "gpu_renderer": "ANGLE (Intel, Mesa Intel(R) HD Graphics 3000 (SNB GT2), OpenGL 4.6)",
  "timezone": "Africa/Nairobi",
  "canvas_seed": 123456789,
  "audio_seed": 987654321,
  "webgl_seed": 555555555,
  "font_seed": 111111111
}

What Each Field Means

Field	Source	Purpose
`cpu_cores`	`std::thread::hardware_concurrency()`	Browser fingerprint
`ram_gb`	`/proc/meminfo` (Linux)	Browser fingerprint
`screen_resolution`	`QGuiApplication::primaryScreen()`	Viewport spoofing
`gpu_vendor`	`/sys/class/drm/card0/device/vendor`	WebGL spoofing
`gpu_renderer`	OpenGL query	WebGL spoofing
`timezone`	`QTimeZone::systemTimeZoneId()`	Timezone spoofing
`canvas_seed`	Random	Canvas fingerprint noise
`audio_seed`	Random	Audio fingerprint noise
`webgl_seed`	Random	WebGL fingerprint noise
`font_seed`	Random	Font fingerprint noise

⚠️ DO NOT EDIT THIS FILE

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   WARNING: Do NOT modify identity.json manually                │
│                                                                 │
│   - Breaks fingerprint consistency                             │
│   - May make browser detectable                                │
│   - Invalid values cause crashes                               │
│                                                                 │
│   Delete it → Piggy regenerates fresh identity                 │
│   Keep it → Consistent fingerprint across restarts             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Reset Identity

bash

# Stop Piggy
pkill nothing-browser-headless

# Delete identity.json
rm identity.json

# Restart — new identity generated
./nothing-browser-headless

`profile.json` — Browser Settings

Generated From `identity.json`

Piggy builds profile.json using the hardware fingerprint:

json

{
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
  "sec_ch_ua": "\"Google Chrome\";v=\"124\", \"Chromium\";v=\"124\", \"Not-A.Brand\";v=\"99\"",
  "platform": "Linux x86_64",
  "chrome_version": 124,
  "language": "en-US",
  "gpu_renderer": "ANGLE (Intel, Mesa Intel(R) HD Graphics 3000 (SNB GT2), OpenGL 4.6)",
  "gpu_vendor": "Google Inc. (Intel)",
  "timezone": "Africa/Nairobi"
}

What Piggy Does With These Values

Field	Used For
`user_agent`	HTTP `User-Agent` header + `navigator.userAgent`
`sec_ch_ua`	`Sec-Ch-Ua` HTTP header (Chrome's User-Agent Client Hints)
`platform`	`navigator.platform`
`chrome_version`	Version in `Sec-Ch-Ua` and JS APIs
`language`	`Accept-Language` header + `navigator.language`
`gpu_renderer`	WebGL `UNMASKED_RENDERER_WEBGL`
`gpu_vendor`	WebGL `UNMASKED_VENDOR_WEBGL`
`timezone`	`Intl.DateTimeFormat().resolvedOptions().timeZone`

✅ SAFE TO EDIT

You can modify profile.json while Piggy is running:

bash

# 1. Edit profile.json
nano profile.json

# 2. Change user_agent to something else
{
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/124.0.0.0"
}

# 3. Hot reload from TypeScript
await piggy.sessionReload();

# 4. All new requests use the new User-Agent

Common Profile Tweaks

Change User-Agent to Windows

json

{
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/124.0.0.0 Safari/537.36",
  "platform": "Win32",
  "sec_ch_ua_platform": "\"Windows\""
}

Change Language

json

{
  "language": "ja-JP",
  "accept_language": "ja-JP,ja;q=0.9,en;q=0.8"
}

Change Timezone

json

{
  "timezone": "Asia/Tokyo"
}

How Fingerprint Spoofing Works

DocumentCreation Injection

Unlike Puppeteer/Playwright that inject scripts after page load, Piggy injects at DocumentCreation — before any page JavaScript runs.

Timeline:
────────────────────────────────────────────────────────────────►

Page starts          DocumentCreation    Page JavaScript runs
      │                    │                    │
      ▼                    ▼                    ▼
┌─────────┐          ┌──────────┐          ┌─────────┐
│  HTML   │          │  Piggy   │          │ Website │
│ parsed  │ ──────►  │ injects │ ──────►  │  runs   │
│         │          │ spoofed  │          │  its    │
│         │          │  values  │          │ scripts │
└─────────┘          └──────────┘          └─────────┘

Spoofed values are already present when website scripts run.
No "before/after" detection possible.

What Gets Spoofed

API	Spoofed Value
`navigator.webdriver`	`undefined` (not present)
`navigator.plugins`	Chrome PDF Plugin, PDF Viewer, Native Client
`navigator.languages`	`["en-US", "en"]`
`navigator.platform`	From `profile.json`
`navigator.userAgent`	From `profile.json`
`navigator.userAgentData`	`{ brands: [...], mobile: false }`
`WebGLRenderingContext.getParameter(37445)`	GPU vendor from `profile.json`
`WebGLRenderingContext.getParameter(37446)`	GPU renderer from `profile.json`
`CanvasRenderingContext2D.getImageData()`	±1 per-pixel noise (xorshift PRNG)
`AudioContext`	±0.00000005 per-sample noise
`Intl.DateTimeFormat().resolvedOptions().timeZone`	From `profile.json`
`navigator.getBattery()`	Random level between 0.6-1.0
`RTCPeerConnection`	STUN servers stripped (no WebRTC IP leak)
`performance.now()`	Reduced precision (100μs)

Real-World Examples

1. Persistent Identity Across Restarts

typescript

// First run — identity.json generated
// Second run — same identity loaded automatically

await piggy.connect({ host, key });

// Browser fingerprint is identical to previous run
const fingerprint = await piggy.evaluate(() => ({
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  webglVendor: document.createElement('canvas').getContext('webgl')?.getParameter(37445)
}));

console.log("Same fingerprint every run:", fingerprint);

2. Multiple Profiles (Different Identities)

bash

# Create separate directories for different identities
mkdir ./profile-us
cp nothing-browser-headless ./profile-us/
cd ./profile-us
./nothing-browser-headless  # Generates US identity (timezone America/New_York)

mkdir ./profile-jp
cp nothing-browser-headless ./profile-jp/
cd ./profile-jp
./nothing-browser-headless  # Generates JP identity (timezone Asia/Tokyo)

typescript

// Connect to US profile
await piggy.connect({ host: "http://localhost:2005", key: "us-key" });

// Connect to JP profile (different binary instance)
await piggy.connect({ host: "http://localhost:2006", key: "jp-key" });

3. Rotating User-Agent

typescript

import { readFileSync, writeFileSync } from "fs";

const userAgents = [
  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/124.0.0.0",
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/124.0.0.0",
  "Mozilla/5.0 (X11; Linux x86_64) Chrome/124.0.0.0"
];

for (const ua of userAgents) {
  // Update profile.json
  const profile = JSON.parse(readFileSync("./profile.json", "utf-8"));
  profile.user_agent = ua;
  writeFileSync("./profile.json", JSON.stringify(profile, null, 2));
  
  // Hot reload
  await piggy.sessionReload();
  
  // Check new UA
  const currentUA = await piggy.evaluate(() => navigator.userAgent);
  console.log("Now using:", currentUA);
  
  // Scrape with this UA
  await piggy.site.navigate("https://example.com");
}

4. Verify Fingerprint is Working

typescript

// Test what websites see
const fingerprint = await piggy.evaluate(() => ({
  // Navigator properties
  webdriver: (navigator as any).webdriver,
  plugins: navigator.plugins.length,
  languages: navigator.languages,
  platform: navigator.platform,
  userAgent: navigator.userAgent,
  
  // WebGL
  webglVendor: (() => {
    const canvas = document.createElement('canvas');
    const gl = canvas.getContext('webgl');
    return gl?.getParameter(37445); // UNMASKED_VENDOR_WEBGL
  })(),
  
  // Canvas (should have noise, but not detectable as spoofed)
  canvasHash: (() => {
    const canvas = document.createElement('canvas');
    canvas.width = 100;
    canvas.height = 100;
    const ctx = canvas.getContext('2d');
    ctx?.fillRect(0, 0, 100, 100);
    return canvas.toDataURL().slice(0, 100);
  })(),
  
  // Timezone
  timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
}));

console.log("Fingerprint:", fingerprint);
// webdriver: undefined ✅
// plugins: 3 ✅
// webglVendor: "Google Inc. (Intel)" ✅
// timezone: matches profile.json ✅

File Format Specifications

`identity.json`

typescript

interface Identity {
  cpu_cores: number;           // 1-128
  ram_gb: number;              // 0.5-512
  screen_resolution: string;   // "1920x1080"
  gpu_vendor: string;          // "Intel", "NVIDIA", "AMD"
  gpu_renderer: string;        // Full renderer string
  timezone: string;            // IANA timezone (e.g., "Africa/Nairobi")
  canvas_seed: number;         // 0-2^31-1
  audio_seed: number;          // 0-2^31-1
  webgl_seed: number;          // 0-2^31-1
  font_seed: number;           // 0-2^31-1
}

`profile.json`

typescript

interface Profile {
  user_agent: string;          // Full browser UA
  sec_ch_ua: string;           // Chrome's Sec-Ch-Ua header
  platform: string;            // "Win32", "MacIntel", "Linux x86_64"
  chrome_version: number;      // 124
  language: string;            // "en-US"
  gpu_renderer: string;        // WebGL renderer string
  gpu_vendor: string;          // WebGL vendor string
  timezone: string;            // IANA timezone
}

Troubleshooting

"identity.json not being generated"

Cause: Binary version too old or permissions issue

Fix:

bash

# Check binary version
./nothing-browser-headless --version

# Ensure write permissions in current directory
chmod 755 .

"profile.json values not applying"

Cause: Need to reload after editing

Fix:

typescript

await piggy.sessionReload();

"Website still detects automation"

Cause: Some bot detection looks for other signals

Check:

typescript

// Enable human mode for behavioral patterns
piggy.actHuman(true);

// Use headful mode (some sites detect headless)
await piggy.launch({ binary: "headful" });

"Different fingerprint on each run"

Cause: identity.json deleted or not readable

Fix: Keep identity.json — don't delete it between runs

Next Steps

Cookies Hot Reload — Edit cookies while browser runs
Session Persistence — Save WebSocket frames and pings
Anti-Detection — Complete anti-detection guide

Nothing Ecosystem · Ernest Tech House · Kenya · 2026

🆔 Identity & Profile — Hardware Fingerprint & Browser Settings ​

Overview ​

Quick Start ​

File Locations ​

identity.json — Hardware Fingerprint ​

Generated On First Run ​

What Each Field Means ​

⚠️ DO NOT EDIT THIS FILE ​

Reset Identity ​

profile.json — Browser Settings ​

Generated From identity.json ​

What Piggy Does With These Values ​

✅ SAFE TO EDIT ​

Common Profile Tweaks ​

Change User-Agent to Windows ​

Change Language ​

Change Timezone ​

How Fingerprint Spoofing Works ​

DocumentCreation Injection ​

What Gets Spoofed ​

Real-World Examples ​

1. Persistent Identity Across Restarts ​

2. Multiple Profiles (Different Identities) ​

3. Rotating User-Agent ​

4. Verify Fingerprint is Working ​

File Format Specifications ​

identity.json ​

profile.json ​

Troubleshooting ​

"identity.json not being generated" ​

"profile.json values not applying" ​

"Website still detects automation" ​

"Different fingerprint on each run" ​

Next Steps ​

🆔 Identity & Profile — Hardware Fingerprint & Browser Settings

Overview

Quick Start

File Locations

`identity.json` — Hardware Fingerprint

Generated On First Run

What Each Field Means

⚠️ DO NOT EDIT THIS FILE

Reset Identity

`profile.json` — Browser Settings

Generated From `identity.json`

What Piggy Does With These Values

✅ SAFE TO EDIT

Common Profile Tweaks

Change User-Agent to Windows

Change Language

Change Timezone

How Fingerprint Spoofing Works

DocumentCreation Injection

What Gets Spoofed

Real-World Examples

1. Persistent Identity Across Restarts

2. Multiple Profiles (Different Identities)

3. Rotating User-Agent

4. Verify Fingerprint is Working

File Format Specifications

`identity.json`

`profile.json`

Troubleshooting

"identity.json not being generated"

"profile.json values not applying"

"Website still detects automation"

"Different fingerprint on each run"

Next Steps