👻 Ghost Shell - Web Terminal & Browser Gateway

A high-performance Web Terminal and Browser Gateway built with Next.js 15, Socket.io, xterm.js, and Playwright.

🚀 One-Command Setup for AI VMs

If you are running this inside an AI terminal or a fresh Linux VM, run this exact block:

# 1. Enter the project and install dependenciescd ghost-shell && npm install
# 2. Start the Terminal Backend (Port 3004)cd mini-services/terminal-service && npm install && npx tsx index.ts &# 3. Start the Browser Backend (Port 3005) - OPTIONALcd ../browser-service && npm install && npx playwright install chromium && npx tsx index.ts &# 4. Start the Frontend (Port 3000)cd ../.. && npm run dev &

Alternative: Using Bun (if available)

cd ghost-shell && bun install
cd mini-services/terminal-service && bun install && bun run index.ts &cd ../browser-service && bun install && npx playwright install chromium && bun run index.ts &cd ../.. && bun run dev &

Pro-Tip for your next chat:

Next time you start a fresh chat, you can just tell the AI:

"Git clone [link], look at the README, and follow the 'One-Command Setup for AI VMs' section."

This will tell the AI exactly which directories to enter and which ports to open without you having to guide it step-by-step.

---

🌐 Browser Gateway

The Browser Gateway lets you browse the web visually through a headless browser. Perfect for:

• Viewing localhost apps you're developing
• Browsing external websites from within the terminal
• Testing web applications in sandboxed environments

Access it at:http://localhost:3000/browser

Features:

• Real-time screenshot streaming (~8 FPS)
• Click interaction on any element
• Keyboard input support
• Back/Forward/Refresh navigation
• URL bar with autocomplete

---

🕷️ Example: Installing SpiderFoot (OSINT Tool)

Once Ghost Shell is running and you have terminal access, here's how to install and run SpiderFoot:

# Clone SpiderFoot
git clone https://github.com/smicallef/spiderfoot.git
cd spiderfoot
# Create a virtual environment (IMPORTANT: avoids Python path issues)
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install lxml
sed -i '/lxml/d' requirements.txt # Remove lxml from requirements (already installed)
pip install -r requirements.txt
# Run SpiderFoot web UI
python3 sf.py -l 0.0.0.0:5001

SpiderFoot will be available on port 5001.

---

💡 Why Virtual Environments?

When installing Python tools in ephemeral/sandboxed environments, always use python3 -m venv venv because:

• User-installed packages may not be in Python's default path
• Virtual environments are self-contained and avoid path conflicts
• It "just works" every time

---

🏗️ Architecture

Component	Technology	Port
Frontend	Next.js 15 + xterm.js	3000
Terminal Backend	Node.js + Socket.io (PTY)	3004
Browser Backend	Playwright + Socket.io	3005
Skills	AI capabilities (LLM, TTS, etc.)	/skills

Routes

Route	Description
/	Web Terminal
/browser	Browser Gateway