hypermind

Docker

docker run -d \
  --name hypermind \
  --network host \
  --restart unless-stopped \
  -e PORT=3000 \
  -e ENABLE_CHAT=true \
  -e ENABLE_MAP=true \
  ghcr.io/lklynet/hypermind:latest

⚠️ CRITICAL NETWORK NOTE: Use --network host. This is a P2P application that needs to punch through NATs. If you bridge it, the DHT usually fails, and you will be the loneliest node in the multiverse.

Docker Compose (The Classy Way)

Add this to your docker-compose.yml to permanently reserve system resources for no reason:

services:
  hypermind:
    image: ghcr.io/lklynet/hypermind:latest
    container_name: hypermind
    network_mode: host
    restart: unless-stopped
    environment:
      - PORT=3000
      - ENABLE_CHAT=true
      - ENABLE_MAP=true

Kubernetes (The Enterprise Way)

For when you need your useless counter to be orchestrated by a control plane.

kubectl create deployment hypermind --image=ghcr.io/lklynet/hypermind:latest --port=3000
kubectl set env deployment/hypermind PORT=3000 ENABLE_CHAT=true
kubectl expose deployment hypermind --type=LoadBalancer --port=3000 --target-port=3000

Hypermind is highly configurable. Use these variables to tune your experience.

Feature Flags

Network Tuning

The community has bravely stepped up to integrate Hypermind into critical monitoring infrastructure.

Home Assistant

Do you want your living room lights to turn red when the swarm grows? Of course you do.

The Hypermind HA Integration (installable via HACS) provides:

• RGB Control: 0 nodes = Green. 10,000 nodes = Red.
• Sensors: Swarm health checks and statistics logging.
• WLED Support: Visualize the swarm size on a literal LED strip.

Homepage Dashboard

If it’s not on your dashboard, does it even exist? You can query the /api/stats endpoint to add a widget to gethomepage/homepage.

Add this to your services.yaml:

- Hypermind:
    icon: /icons/hypermind2.png
    href: http://<YOUR_IP>:3000
    widget:
      type: customapi
      url: http://<YOUR_IP>:3000/api/stats
      method: GET
      mappings:
        - field: count
          label: Active
        - field: totalUnique
          label: All Time

To get the icon to work, you have to add the icon to /app/public/icons. See detailed instructions.

API Documentation

For developers who are not satisfied in just looking a number on the screen but are craving to add new features, a comprehensive development API documentation is available in devdocs/API.md.

Available Endpoints:

• GET /api/stats - Current node statistics
• POST /api/chat - Send P2P chat messages
• GET /api/github/latest-release - Latest release information
• GET /events - Server-Sent Events stream for real-time updates
• GET /js/lists.js - Dynamic adjectives/nouns for screenname generation
• GET /js/screenname.js - Screenname generation logic
• GET / - Main HTML page

The documentation includes security best practices, rate limiting guidelines, modular route structure, and examples for creating new endpoints.

Want to contribute? Why? It already does nothing perfectly. But here is how anyway:

# Install dependencies
npm install

# Run the beast
npm start

Simulating a Swarm

You can run multiple instances locally to simulate popularity:

# Terminal 1
PORT=3000 npm start

# Terminal 2
PORT=3001 npm start

They will discover each other via the local network DHT, and the number will become 2. Dopamine achieved.