Installation

Fresh

Source: bible/setup.md

Complete setup from a fresh Windows machine to a running Ghost Engine. Takes 10 to 15 minutes.

Requirements

Requirement	Minimum	Recommended
OS	Windows 10	Windows 11
Node.js	18.0.0	20+ (LTS)
Chrome	Any recent version	Latest stable
RAM	8 GB	16 GB
Disk	2 GB free	10 GB free
Terminal	Any (PowerShell, cmd, Git Bash)	PowerShell 7

Step 1: Clone the repo

cd C:\Users\jennb
git clone <repo-url> browser-sender

Ghost Engine lives inside browser-sender at lib/dna-engine/mini-engine-v2/.

Step 2: Run the install script

cd C:\Users\jennb\browser-sender\lib\dna-engine\mini-engine-v2
node scripts/install.mjs

The install script does 7 things automatically:

1. Checks Node.js version (needs 20+)
2. Checks Chrome is installed
3. Runs npm install to get dependencies
4. Creates 24 data directories (accounts, campaigns, cookies, fingerprints, etc.)
5. Creates .env from .env.example if it does not exist
6. Imports accounts from the browser-sender account registry
7. Verifies the server boots without errors

Expected output:

[1] Checking Node.js version...
    Node.js v20.11.0
[2] Checking Chrome installation...
    Chrome found
[3] Installing dependencies...
    npm install complete
[4] Creating data directories...
    24 directories checked, 24 created
[5] Checking .env configuration...
    .env created from .env.example
[6] Importing accounts...
    50 accounts imported, 0 skipped, 0 errors
    43 accounts with cookies imported
[7] Verifying server boots...
    Server boots without errors

Install flags

Flag	What it does
--skip-npm	Skip npm install if you already have node_modules
--skip-accounts	Skip account import, set up accounts later
--registry <path>	Custom path to registry.json
--cookies <path>	Custom path to cookies directory

Step 3: Configure .env

Open .env and set your API keys:

# Server
GHOST_ENGINE_PORT=4700
GHOST_ENGINE_API_KEY=ghost-engine-key

# Encryption (defaults to machine-specific key if unset)
# MINI_ENGINE_KEY=your-32-char-encryption-key

# Captcha solver
# CAPTCHA_SERVICE=2captcha
# CAPTCHA_API_KEY=your-captcha-api-key

# Vision provider (needed for ghost-mode navigation)
# VISION_PROVIDER=claude
# ANTHROPIC_API_KEY=your-claude-api-key
# OLLAMA_URL=http://127.0.0.1:11434
# OLLAMA_VISION_MODEL=llava

# Storage paths
# GHOST_FINGERPRINT_DIR=./data/mini-engine-v2/fingerprints
# MINI_ENGINE_COOKIE_DIR=./data/mini-engine/cookies

Required for basic operation: port and API key. Defaults work.

Required for ghost mode: a vision provider (Claude, OpenAI, or local Ollama).

Required for CAPTCHA: a captcha service API key.

Step 4: Import accounts (if skipped)

If you have an existing account registry from browser-sender:

node scripts/setup.mjs

With custom paths:

node scripts/setup.mjs --registry /path/to/registry.json --cookies /path/to/login-results/

Dry run first:

node scripts/setup.mjs --dry-run

The account import reads registry.json, creates a DAM card per account, imports saved cookies, and assigns each account a proxy, fingerprint, persona data, and cookie jar.

Step 5: Start the server

node server.mjs

Expected output:

[ghost-engine] Listening on http://localhost:4700
[ghost-engine] Loaded 109 plugins, 704 routes
[ghost-engine] Account store: 50 accounts loaded

Open http://localhost:4700/ to see the dashboard.

Step 6: Verify

# Health check
curl http://localhost:4700/health

# List accounts
node cli.mjs accounts list

# Army status
curl http://localhost:4700/accounts/army-status

# Launch a test browser
curl -s -X POST http://localhost:4700/browser/launch \
  -H "Content-Type: application/json" \
  -H "x-api-key: ghost-engine-key" \
  -d '{"headless":false}'

Data directories

The install script creates these under the engine root:

data/
  ghost-engine/
    accounts/           # DAM cards
    armies/             # army group definitions
    backlink-targets/   # target sites for backlinks
    backlinks/          # backlink submission records
    brand-bombs/        # brand bomb campaign data
    campaigns/          # CTR campaign configs
    cascade-log/        # cascade execution logs
    citation-profiles/  # NAP citation data
    citation-submissions/
    fingerprints/       # generated browser fingerprints
    google-ctr/         # Google CTR round results
    local-seo-audits/   # local SEO audit reports
    ranks/              # rank tracking snapshots
    results/            # search result captures
    review-campaigns/   # review campaign data
    schedules/          # scheduled job configs
    sessions/           # browser session data
    social-campaigns/   # social posting campaigns
    warmup-plans/       # account warmup schedules
    workflows/          # multi-step workflow definitions
    yt-comment-campaigns/
  mini-engine-v2/
    profiles/           # Chrome profile directories
    fingerprints/       # fingerprint snapshot files
  mini-engine/
    cookies/            # encrypted cookie jars

Troubleshooting

Server will not start

• Port in use: another process on 4700. Kill it or change GHOST_ENGINE_PORT in .env
• Module not found: run npm install again
• Node version: must be 18+ (20+ recommended). Check with node -v

Accounts not importing

• Registry not found: check the path to registry.json. Default looks for browser-sender/data/account-identity/registry.json
• Zero cookies: cookie directory might be empty. Accounts will work but need fresh login

Browser will not launch

• Chrome not found: install Google Chrome (not Chromium). The engine looks in standard install paths
• Profile locked: another Chrome instance is using the profile. Close it first

Ghost mode not working

• No vision provider: set VISION_PROVIDER and the matching API key in .env
• Window not focused: ghost mode requires the browser window to have OS focus. Only one ghost session at a time on desktop

Next steps

• Quickstart: the first 10 minutes
• Runbook: every command and recovery procedure
• Concepts: how the system works