localhost-gallery-agent

Local agent for Localhost Gallery. Scans your machine for running development servers and streams the data to the dashboard via WebSocket.

Quick Start

npx localhost-gallery-agent

Or if you have it installed globally:

localhost-gallery-agent

How It Works

1. Visit the dashboard: localhost-ten-tau.vercel.app
2. Run the agent on your machine: npx localhost-gallery-agent
3. Dashboard auto-connects and displays your local dev servers

The dashboard connects to ws://localhost:9876 on YOUR machine, so you see YOUR servers. Everyone uses the same dashboard URL but sees their own local services.

┌─────────────────────────────────────────────────────┐
│  Your Browser                                       │
│  ┌───────────────────────────────────────────────┐  │
│  │  localhost-ten-tau.vercel.app                 │  │
│  │  Connects to ws://localhost:9876              │  │
│  └──────────────────────┬────────────────────────┘  │
│                         │                           │
│  ┌──────────────────────▼────────────────────────┐  │
│  │  Your Machine (npx localhost-gallery-agent)   │  │
│  │  - Scans ports every 3 seconds                │  │
│  │  - Sends data via WebSocket                   │  │
│  │  - Handles kill process requests              │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Security

• Localhost-only binding: The agent only listens on 127.0.0.1:9876, not 0.0.0.0. This means only local connections are accepted.
• No auth required: Since you explicitly run the agent and it only accepts localhost connections, no authentication is needed.
• Kill validation: You can only kill processes that are in the currently scanned port list.

WebSocket Protocol

Server → Client

// Port data (sent every 3 seconds)
{ type: 'ports', data: PortInfo[], timestamp: number }

// SSH connections (sent every 3 seconds)
{ type: 'ssh', data: SSHConnection[], timestamp: number }

// Kill result
{ type: 'kill_result', success: boolean, message: string, pid: number }

// Heartbeat response
{ type: 'pong', timestamp: number }

Client → Server

// Kill a process (works for both ports and SSH connections)
{ type: 'kill', pid: number }

// Heartbeat
{ type: 'ping' }

SSH Connection Detection

The agent also detects active SSH client connections, including:

• Remote host and user
• SSH tunnels (local and remote port forwards)
• Connection uptime
• Remote IP address

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

Scanned Ports

The agent scans these port ranges:

• 3000-3010 (Next.js, React, etc.)
• 4000-4010
• 5000-5010 (Vite, Flask, etc.)
• 5173, 5174 (Vite)
• 8000, 8080, 8888, 8443 (Django, generic servers)
• 9000, 9090

Detected Frameworks

The agent can detect and identify:

• Frontend: Next.js, Vite, Create React App, Vue CLI, Nuxt, Remix, Astro, SvelteKit, Gatsby, Webpack, Parcel
• Backend: Express, NestJS, Fastify, Hono, Django, Flask, FastAPI, Rails, Laravel, Go, Rust
• Database: PostgreSQL, MySQL, MongoDB, Redis
• Tools: Storybook, Prisma Studio, Drizzle Studio, GraphQL Playground