🛡️ Homebox - Cyber-Command Remote PC Management System

Homebox is a high-performance, single-binary, remote PC management dashboard designed to run autonomously on a Raspberry Pi (or any Linux/macOS server) within your local area network (LAN). It provides real-time multi-device monitoring, Wake-on-LAN (WoL) remote power-on capabilities, and a NAT/Firewall friendly outbound MQTT architecture powered by an embedded Mochi MQTT broker to securely send power actions and gather real-time telemetry from your target systems.

---

✨ Key Features

• 🚀 Single-Binary Embedded Cyber-Command Dashboard: Built using Go embed.FS to bundle all HTML templates, static styles, JavaScript, and dynamic PowerShell installer templates directly into a single self-contained executable. No Nginx or external web servers required.
• 🖥️ Built-in Clientless HTML5 Web RDP (noVNC Canvas Engine): Seamless remote access directly from any modern browser via embedded VNC (RFB on port 5900) and WebSocket tunneling (/tunnel?port=5900&proto=rdp). Includes pixel-perfect virtual desktop mouse mapping (MOUSEEVENTF_VIRTUALDESK), right-click context menu protection, and universal keyboard symbol injection without external browser plugins.
• 🔒 Agent-Centric Winlogon Pre-Login Remote Control (Session 1 Penetration): On Windows targets, HomeboxAgent.exe (Session 0 SYSTEM service) dynamically duplicates its token to launch HomeboxAgent.exe --rdp-worker directly into Session 1. Combined with Win32 OpenInputDesktop hooking (winsta0\Winlogon / winsta0\Default), operators can view the Windows Login Screen, enter passwords remotely upon boot, and seamlessly transition to user desktops without disconnection.
• 🧹 Anti-Duplication Tray & Clean Worker Lifecycle (1 Tray per Session): Strict process deduplication ensures HomeboxTray.exe runs exactly once per logged-in user exclusively for the taskbar icon. Automatic process management (KillAllRDPWorkers) tracks workerPID and executes WMI/PowerShell cleanup upon Quit or service stops, leaving zero orphan processes in Task Manager.
• ⚡ Instant Boot Discovery & Telemetry Recovery (TriggerInstantBeacon): Accelerated DHCP network retry intervals (1s) ensure PCs register as Online instantaneously right after boot. Pre-login CPU/RAM/GPU telemetry uses explicit 150ms sampling windows (gopsutil) to guarantee reliable metric broadcasting across Session 0 before any user logs in.
• ⚡ Outbound-Only MQTT Control (NAT & Firewall Friendly): Replaces insecure SSH configurations and legacy inbound UDP command ports. The target agent connects outbound to the embedded server broker (port 1883). All commands (Shutdown, Restart) are delivered securely over this connection with direct local HTTP port 8999 LAN fallback for Smart Home integrations.
• 📊 Real-Time Hardware Telemetry & SSE Diagnostics: Gathers real-time CPU load, CPU temperatures, RAM usage, and NVIDIA/AMD GPU stats on the agent using gopsutil and sensor APIs, streaming them directly to the Web UI via Server-Sent Events (SSE).
• 🐧 Universal OS Service Agents (Windows, Linux, macOS): Automated native daemon auto-installers. Registers target agents as native system services (Windows Service Controller, Linux Systemd, and macOS Launchd) via root/sudo check-ins with localized English uninstaller scripts (uninstall.ps1 / uninstall.sh).
• 🌗 Modern Dark & Light Mode UI: Minimalist, glassmorphism-inspired interface powered by Tailwind CSS with instant theme toggle persistence (localStorage) and automatic fallback to OS preferences (prefers-color-scheme).
• 📦 Zero-Configuration Agent Auto-Discovery: Network-discovered agents appear in a "Discovered Devices (Pending Approval)" panel. Admins can claim and approve devices with a single click.

---

🏛️ System Architecture

graph TD
    User["🌐 Admin Browser (Dashboard UI / noVNC Canvas)"] -->|HTTP / SSE / RDP WebSocket Tunnel| Server["🖥️ Homebox Server (Pi / Linux arm64)"]
    Server -->|Embedded Mochi MQTT Port 1883 / LWT| Agent["🛡️ HomeboxAgent.exe (Session 0 SYSTEM Service)"]
    Server -->|Direct LAN Fallback HTTP Port 8999| Agent
    Server -->|Wake-on-LAN Magic Packet UDP Port 9| TargetPC["💻 Target PC Hardware"]
    
    subgraph Windows Target PC
        Agent -->|InitiateSystemShutdownExW| Shutdown["⚙️ OS Shutdown / Reboot"]
        Agent -->|gopsutil 150ms Sample Window| Telemetry["📊 CPU, RAM & GPU Telemetry"]
        Agent -->|CreateProcessAsUserW Session 1 Duplication| Worker["🖥️ HomeboxAgent.exe --rdp-worker (Session 1 SYSTEM)"]
        Agent <-->|IPC Port 8998 Toggle Commands| Tray["🎯 HomeboxTray.exe (Session 1 Logged-In User UI)"]
        Worker -->|OpenInputDesktop winsta0\Winlogon & Default| Screen["📸 VNC Screen Capture & Virtual Desk Mouse Control"]
    end

Loading

🛠️ Tech Stack & Key Dependencies

Homebox is built with a lightweight, secure, and purely CGO-free architecture. Below is the list of core components and libraries used:

• Go Runtime: v1.26.5 (Pure Go runtime framework)
• Embedded MQTT Broker: github.com/mochi-mqtt/server/v2 (v2.7.9) - High-performance embeddable MQTT v5 broker
• MQTT Client: github.com/eclipse/paho.mqtt.golang (v1.5.1) - Standard Go MQTT client for messaging routing
• Embedded Database: modernc.org/sqlite (v1.53.0) - Pure Go SQLite driver (CGO-free for safe cross-compilation)
• Hardware Telemetry: github.com/shirou/gopsutil/v3 (v3.24.5) - Cross-platform CPU, memory, and sensor diagnostics
• Desktop System Tray: github.com/getlantern/systray (v1.2.2) - Cross-platform UI tray library
• WebSockets: github.com/gorilla/websocket (v1.5.3) - Tunnel proxy and clientless VNC/SSH terminal bridge
• Configuration Manager: github.com/spf13/viper (v1.21.0) - Resilient .env loading and environment mapping
• UUID v4 Utility: github.com/google/uuid (v1.6.0) - Cryptographically secure unique hardware identifier generation

Project Directory Layout

homebox/
├── cmd/
│   ├── homebox/             # Entrypoint for Raspberry Pi / Linux Management Server
│   ├── homebox-agent/       # Entrypoint for Target PC Secure Daemon
│   └── homebox-tray/        # Entrypoint for Target Agent System Tray App (GUI)
├── internal/                # Encapsulated Clean Architecture Core Layers
│   ├── config/              # Environment Variable Loader & Configuration Structs
│   ├── domain/              # Domain Models, Interfaces, and Entities
│   ├── repository/          # Infrastructure Adapters (WoL, SQLite, ICMP/TCP Monitor)
│   ├── usecase/             # Business Logic (Auth, PC Operations, Real-Time Monitoring)
│   ├── delivery/            # HTTP Handlers, Routers, and Auth Middlewares
│   └── agent/               # Agent-specific startup, system tray, and daemon modules
├── scripts/                 # Standalone PowerShell Installation Scripts
├── web/                     # Embedded Web UI Resources (embed.FS)
│   ├── templates/           # HTML Templates (index.html, device_detail.html, etc.)
│   └── static/              # CSS, JS (app.js)
├── Makefile                 # Automated Build, Test, and Cross-Compilation Toolchain
└── .env.example             # Template Configuration File

---

⚙️ Configuration Reference (.env)

Create a .env file in your server working directory (or copy from .env.example). Below is the complete reference of all configuration parameters:

Variable	Default Value	Description
🔐 Web Application & Security
ADMIN_USERNAME	admin	Username for dashboard login authentication.
ADMIN_PASSWORD	homebox123	Password for dashboard login authentication.
APP_PORT	8080	HTTP port on which the Homebox web server listens.
APP_SECRET	super-secret-...	Cryptographic secret for signing HTTP session cookies.
MONITOR_INTERVAL_SECONDS	3	Period in seconds for SSE telemetry broadcasts.
⚡ Embedded MQTT Configuration
MQTT_PORT	1883	TCP listening port for the embedded Mochi MQTT Broker.
AGENT_SECRET_KEY	homebox-secure-...	Shared HMAC secret token compiled securely into target agent binaries.
📱 Telegram Alerting
TELEGRAM_BOT_TOKEN	(empty)	Telegram Bot Token obtained via @BotFather.
TELEGRAM_CHAT_ID	(empty)	Telegram Chat ID or Group ID where security alerts are sent.

---

🚀 Quick Start Guide

Step 1: Server Setup (Raspberry Pi / Linux / macOS)

1. Clone the repository and enter the directory:

   git clone https://github.com/kal72/homebox.git
   cd homebox

2. Configure environment settings:

   cp .env.example .env
   nano .env  # Edit ADMIN_PASSWORD and AGENT_SECRET_KEY

3. Run unit tests and build binaries:

   make test
   make build

   This command compiles optimized binaries into the bin/ directory:

   • bin/homebox (Native OS binary)
   • bin/homebox-linux-arm64 (Cross-compiled for Raspberry Pi 64-bit)
   • bin/homebox-agent-linux-arm64 (Cross-compiled agent daemon for Linux)
   • bin/homebox-agent-windows-amd64.exe (Cross-compiled Windows agent daemon)

4. Launch the Homebox Server:

   ./bin/homebox

   Open your browser and navigate to http://<YOUR_SERVER_IP>:8080.

---

Step 2: Target PC Setup (Windows / Linux / macOS)

Windows Installation:

1. Open PowerShell as Administrator on your Windows Target PC.
2. Run the following command (replace 192.168.1.100:8080 with your Raspberry Pi server's IP address and port):

   irm http://192.168.1.100:8080/agent/install.ps1 | iex

Linux & macOS Installation:

1. Open terminal on the target Unix machine.
2. Run the following one-line command to install the agent daemon as a system service:

   curl -sSL http://192.168.1.100:8080/agent/install.sh | sudo bash

---

🛠️ Makefile Commands Reference

Command	Description
make test	Executes all unit tests across internal/ packages.
make build	Compiles server and agent binaries for all target platforms (Windows, Linux, macOS).
make run	Starts the local homebox server directly via go run ./cmd/homebox.
make clean	Removes all compiled binaries inside the bin/ directory.

---

🔒 Security Best Practices

• Outbound-Only Port Footprint: Zero inbound ports are required on client machines. Agents only connect outbound via TCP port 1883 to the server.
• Zero-Plaintext Agent Keys: AGENT_SECRET_KEY is never transmitted in URL parameters, never written inside installation scripts, and never saved in a .env file on client PCs.
• Information Leakage Prevention: Public endpoints and API responses strip sensitive network topology identifiers (CheckPort, MACAddress, BroadcastAddress, cryptographic keys) to prevent reconnaissance.