First Launch & Setup
Get PhantomYerra running on Windows, macOS, or Linux — from installation through your first successful scan.
Launch Sequence — Every Platform
Each time PhantomYerra starts it runs a four-step boot sequence before the main application becomes available. The sequence is fully automatic — you only need to act on Step 4.
-
1
Splash Screen — Capability Cards Load
A dark splash screen appears immediately. It displays a grid of capability cards — one per scanning engine: Web Pentest, Network Pentest, API Pentest, SAST, Cloud Security, AI/LLM Security, and more.
Each card shows a live activity message that cycles automatically every ~1 second:
Web Pentest → "Validating CVEs..." Network & Infra → "Installing updates..." API Testing → "Identifying latest attacks..." SAST Engine → "Loading language parsers..." Cloud Security → "Syncing threat intelligence..."At the bottom of the splash, a narrative status line cycles continuously in a loop — it never stops. Example messages:
"All systems armed and ready" "Zero-day intelligence active" "AI orchestration online" "60+ attack tools standing by" "CVE database synchronized"💡 The splash screen runs for a minimum of 9 seconds even if all tools load faster, so you have time to see which capabilities are arming. The backend Python engine and all intelligence databases are initialised during this window. -
2
System Compatibility Check Screen
After the splash completes (tools loaded + 9-second minimum elapsed), the splash fades out and the System Compatibility Check screen takes over. This screen verifies that the host machine meets all runtime requirements before the main window opens.
The screen shows a live checklist — each row turns green as it is confirmed:
✓ Operating System Windows 11 Pro 23H2 (or your OS) ✓ Processor Intel Core i7-12700H × 20 cores ✓ Memory 32 GB RAM (18 GB free) ✓ Python Engine Connected (localhost:8731) ✓ Security Tools 60+ Ready ✓ CVE Intelligence Active (synced today) ✓ Armed License [green badge]The Armed License badge appears in the top-right corner of the checklist panel once a valid license is confirmed.
While the checklist is displayed, the animated status line at the bottom of the screen continues cycling through readiness messages — this confirms the backend is fully alive and responsive.
💡 If any row shows a red ✗, hover over it for a one-line diagnosis. Common causes: Python engine not yet started (wait 5 seconds and it will resolve), CVE intelligence never synced (internet required on first run), or a missing tool binary. -
3
Click "▶ Launch PhantomYerra"
Once all compatibility checks are green, a large ▶ Launch PhantomYerra button becomes active at the bottom of the compatibility screen. Click it to open the main application window.
⏱ Auto-fallback: If you do not click the button within 45 seconds, PhantomYerra launches automatically. This ensures unattended startup (e.g. system boot, kiosk mode) is never blocked waiting for user input. -
4
Main Application Opens
The main PhantomYerra window opens to the Home Screen. All 60+ attack tools, AI orchestration, and CVE intelligence are fully loaded and ready. No further setup is required for subsequent launches — the boot sequence completes in under 10 seconds once dependencies are installed.
Platform Installation
Select your operating system below for step-by-step installation instructions. The launch sequence above applies to all platforms once installation is complete.
Prerequisites
- Windows 10 Pro / Enterprise v2004+ or Windows 11
- WSL 2 enabled (required for Linux scan tools)
- 8 GB RAM minimum — 16 GB recommended
- 50 GB free disk space
- Internet connection for initial tool download
- Administrator privileges for installer
-
1
Run the PhantomYerra Installer
Double-click
PhantomYerra-Setup-1.0.0-win.exe. Accept the UAC prompt. The installer automatically detects and installs all prerequisites.💡 The installer runsscripts/install/windows_install.ps1under the hood — it will enable WSL2, install Python 3.12, Node.js 20 LTS, pnpm, and Redis. -
2
Wait for Dependency Installation
The installer shows a progress screen while it installs scan tools into
C:\PhantomYerra\tools\. This takes 5–15 minutes on first run depending on internet speed.Installing: nuclei v3.x ✓ Installing: nmap 7.94 ✓ Installing: sqlmap 1.8 ✓ Installing: ffuf v2.x ✓ Installing: subfinder v2.x ✓ Installing: httpx v1.x ✓ Installing Python packages ✓ Installing Node packages ✓ -
3
Launch PhantomYerra
Click the desktop shortcut or find PhantomYerra in Start Menu. The Electron app opens and the FastAPI backend starts automatically on
localhost:8731.The 4-step launch sequence described at the top of this page now runs: Splash Screen → System Compatibility Check → click ▶ Launch PhantomYerra → main app opens.
-
4
Complete the Setup Wizard
On first launch, the Setup Wizard appears automatically after the main window opens. It walks you through: workspace directory selection, database initialization, and optional AI key entry.
💡 You can skip AI key setup and add it later via Settings → AI Configuration. -
5
Verify Platform Status
Check the status bar at the bottom of the app. All indicators should be green:
● API Server : Running (localhost:8731) ● Database : Connected (SQLite WAL) ● Redis : Running (localhost:6379) ● Tools : 60/60 found ● License : Active -
6
Run a Test Scan Against localhost
On the Home Screen, click Web App Pentest. In the wizard, set target to
http://localhost, select Test/Lab environment, and run a quick scan to confirm everything is working.
Common Issues
The FastAPI backend (sidecar) takes 3–8 seconds to start. The compatibility screen polls for it automatically every 2 seconds for up to 60 seconds. Wait a moment — the row will turn green once the engine is ready. If it stays red after 60 seconds, check that no other process is using port 8731: run netstat -ano | findstr 8731 (Windows) or lsof -i :8731 (macOS/Linux).
CVE intelligence requires an internet connection on first run to seed the local database. Ensure the machine has outbound internet access, then go to Settings → Intelligence → Sync Now. Subsequent launches check a 24-hour staleness window — if data was synced today, the screen will show Active instantly without re-downloading.
The launch button activates only when the Python Engine row is green (connected). All other rows — Security Tools, CVE Intelligence — can be yellow/partial and the button will still activate. If the engine row is red, see the "Python Engine: Connecting…" issue above. If the button never appears, try restarting the app — the compatibility screen has a 45-second auto-fallback that will launch anyway.
Activity messages cycle every 1.1 seconds and are staggered per card. If the splash screen loads but all cards are blank or frozen, the renderer may have encountered a JavaScript error. Press Ctrl+Shift+I to open DevTools, check the Console tab for errors, then press Ctrl+R to reload. If the issue persists, reinstall the application.
Another process is using port 8731. Run netstat -ano | findstr 8731 (Windows) or lsof -i :8731 (macOS/Linux) to identify the conflicting process. Kill it or change the API port in config/default_config.json under api.port.
Run in PowerShell as Administrator: wsl --install, then restart your computer. WSL2 requires Windows 10 Build 19041 or higher. After restart, run the PhantomYerra installer again.
Manually trigger the tool installer: Settings → Tools → Re-run Tool Installer. You can also install individual tools from the Tools panel. Check D:\PhantomYerra\tools\ to confirm tool binaries exist.
Delete data/phantomyerra.db and restart the app. The database will be recreated automatically. This is safe to do on a fresh install — no scan data will be lost.
This usually means the Vite dev server or built renderer failed to load. Check output.log for errors. Try: View → Reload (Ctrl+R). If it persists, reinstall the app — do not delete data/.