{"id":50368484,"url":"https://github.com/rozsival/panther-minor-controller","last_synced_at":"2026-05-30T05:30:45.816Z","repository":{"id":355631597,"uuid":"1217824879","full_name":"rozsival/panther-minor-controller","owner":"rozsival","description":"🖲️ Remote control for Panther Minor AI workstation","archived":false,"fork":false,"pushed_at":"2026-05-19T16:50:04.000Z","size":135,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T20:04:04.048Z","etag":null,"topics":["ai-workstation","controller","raspberry-pi","remote-control"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rozsival.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-22T08:55:39.000Z","updated_at":"2026-05-19T16:50:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rozsival/panther-minor-controller","commit_stats":null,"previous_names":["rozsival/panther-minor-controller"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/rozsival/panther-minor-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozsival%2Fpanther-minor-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozsival%2Fpanther-minor-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozsival%2Fpanther-minor-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozsival%2Fpanther-minor-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rozsival","download_url":"https://codeload.github.com/rozsival/panther-minor-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rozsival%2Fpanther-minor-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33681809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-workstation","controller","raspberry-pi","remote-control"],"created_at":"2026-05-30T05:30:39.671Z","updated_at":"2026-05-30T05:30:45.810Z","avatar_url":"https://github.com/rozsival.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🖲️ Panther Minor Controller\n\n### Remote control for [Panther Minor](https://github.com/rozsival/panther-minor) AI workstation\n\n![Platform](https://img.shields.io/badge/Platform-Raspberry%20Pi%20-0A84FF)\n![Architecture](https://img.shields.io/badge/Architecture-ARM-E01F27)\n![Language](https://img.shields.io/badge/Language-Rust-FE5E00)\n\nLight-weight secure remote control for Panther Minor in a single binary that runs on a\n**Raspberry Pi Zero 2 W**. It provides a web interface and API to **power up**, **power down**, **force shutdown**, and\n**hard reset** the workstation remotely, with real-time status tracking and confirmation.\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n| Feature                  | What it gives you                                                                           |\n| ------------------------ | ------------------------------------------------------------------------------------------- |\n| **Web dashboard**        | Clean, responsive interface with real-time status, action buttons, and confirmation flow    |\n| **REST API**             | Full programmatic control — integrate with scripts, automation, or other tools              |\n| **Status tracking**      | TCP reachability polling keeps `/api/health` and `/api/status` aligned with the real device |\n| **Action confirmation**  | Dashboard keeps polling status after each action and during normal viewing                  |\n| **Secure remote access** | Tailscale-only access, hardened SSH, firewall, and fail2ban                                 |\n| **Zero-touch install**   | One script to prepare the Raspberry Pi, another to install and daemonize the controller     |\n\n---\n\n## 🏗️ Architecture\n\n```mermaid\nflowchart LR\n    U[Browser / Clients] --\u003e D[Dashboard \u0026 API]\n    D --\u003e|Tailscale| C[Controller App]\n    C --\u003e R[Relay Module]\n    R --\u003e P[Panther Minor]\n\n    C --\u003e S[Power State Tracker]\n    S --\u003e|Polls status| C\n```\n\nThe Controller runs on a **Raspberry Pi Zero 2 W** wired to a **5V relay module** that bridges the Panther Minor's power button pins (PWR+ ↔ PWR-). A short relay closure simulates a button press — **0.5s for power on/off**, **5s for force shutdown**. Communication between your browser and the Pi happens exclusively over **Tailscale**.\n\n---\n\n## 🧰 Prerequisites\n\n### Hardware\n\n| Component    | Recommendation                     |\n| ------------ | ---------------------------------- |\n| Board        | **Raspberry Pi Zero 2 W**          |\n| Power supply | Official Pi Zero USB PSU           |\n| MicroSD card | 16 GB or more, Class 10 or U1      |\n| Relay module | 5V single-channel with optocoupler |\n| Wiring       | Jumper wires (female-to-female)    |\n\n### Wiring\n\nConnect the relay module to the Raspberry Pi GPIO as follows:\n\n| Relay Pin | Pi Pin (BCM)       | Purpose                            |\n| --------- | ------------------ | ---------------------------------- |\n| VCC       | 5V (Pin 2)         | Power                              |\n| GND       | GND (Pin 6)        | Ground                             |\n| IN1       | BCM 17 (Pin 11)    | Signal (configurable via env)      |\n| NC        | —                  | Not used                           |\n| COM       | Panther Minor PWR+ | Connects to power button           |\n| NO        | Panther Minor PWR- | Bridges PWR pins when relay closes |\n\n\u003e [!NOTE]\n\u003e The relay is **active-high**: setting the GPIO pin HIGH closes the relay (shorts the PWR pins). The default GPIO pin\n\u003e is **BCM 17**. Change it via the `GPIO_PIN` environment variable.\n\n### Software\n\n- 🍇 [Raspberry Pi OS Lite](https://www.raspberrypi.com/software/operating-systems/) (64-bit, minimal image)\n- SD card flashed via [Raspberry Pi Imager](https://www.raspberrypi.com/software/)\n- SSH enabled with key auth during flashing\n- Wi-Fi configured during flashing\n- A [Tailscale](https://tailscale.com/) account for secure remote access\n\n---\n\n## 🚀 Quick Start\n\n### 1. Set up the Raspberry Pi\n\nSSH into your Raspberry Pi and run the device setup script:\n\n\u003e [!WARNING]\n\u003e SSH will be available on **port 2222** with **key-based authentication only**.\n\u003e\n\u003e Reconnect with: `ssh -p 2222 \u003cuser\u003e@\u003cpizero-ip\u003e`\n\n```bash\nwget https://github.com/rozsival/panther-minor-controller/releases/download/v1.0.5/setup-device.sh -O setup-device.sh\nsudo bash setup-device.sh\nrm setup-device.sh\n```\n\n### 2. Connect Tailscale\n\nAfter the initial setup authenticate the server to your\n[Tailscale network](https://login.tailscale.com/admin/):\n\n```bash\nsudo tailscale up\n```\n\nFollow the browser link to authenticate. Once connected, access your Raspberry through its Tailscale hostname (e.g. `pi-zero`).\n\n\u003e [!TIP]\n\u003e It is usually best to\n\u003e [disable key expiry](https://login.tailscale.com/admin/machines)\n\u003e for the Pi in Tailscale to avoid losing access.\n\n### 3. Install the controller\n\nAfter the device setup completes, install the controller binary as a `systemd` service:\n\n```bash\nwget https://github.com/rozsival/panther-minor-controller/releases/download/v1.0.5/install-app.sh -O install-app.sh\nsudo bash install-app.sh\nrm install-app.sh\n```\n\n\u003e [!IMPORTANT]\n\u003e Customize variables in `/opt/panther-minor-controller/env` to match your setup.\n\n#### Update the controller\n\nTo update to a newer release, run the update script (it stops the service, replaces the binary, then restarts):\n\n```bash\nwget https://github.com/rozsival/panther-minor-controller/releases/download/v1.0.5/update-app.sh -O update-app.sh\nsudo bash update-app.sh\nrm update-app.sh\n```\n\n### 4. Access the dashboard\n\nOpen your browser and navigate to `http://pi-zero:8080` (replace with your Pi's Tailscale hostname and port if customized). You should see the dashboard with action buttons and real-time status.\n\n---\n\n## ⚙️ What the setup scripts configure\n\n### `setup-device.sh`\n\nPrepares the Raspberry Pi with:\n\n- **Timezone** — sets the system timezone\n- **Essential packages** — core packages with unattended upgrades enabled\n- **SSH hardening** — custom port, key-only auth, disabled root login, restricted users\n- **UFW** — firewall with only allowed SSH port open\n- **GPIO group** — grants the allowed user access to GPIO pins\n- **fail2ban** — brute-force protection\n- **Tailscale** — Tailscale agent installation\n- **Shell** — modern shell prompt for the current user\n\n### `install-app.sh`\n\nInstalls the controller as a managed service:\n\n- Downloads the latest binary from GitHub Releases\n- Creates an environment file at `/opt/panther-minor-controller/env`\n- Installs a `systemd` service (`panther-minor-controller.service`) that starts after Tailscale\n- Enables auto-restart on failure\n\n### `update-app.sh`\n\nUpdates the controller binary without reconfiguring the service:\n\n- Downloads the latest binary from GitHub Releases\n- Prompts for confirmation before overwriting the existing binary\n- Stops the service, replaces the binary, then restarts it\n- Exits with a helpful message if no existing binary is found (suggests `install-app.sh`)\n\n---\n\n## 🖥️ Dashboard\n\nThe web dashboard provides a clean interface with four action buttons:\n\n| Button        | Action                | Relay Behavior              |\n| ------------- | --------------------- | --------------------------- |\n| 🟢 Power On   | Start the workstation | Short press 0.5s            |\n| 💤 Power Off  | Graceful shutdown     | Short press 0.5s (ACPI)     |\n| 🔴 Shutdown   | Force shutdown        | Long press 5s               |\n| 🔄 Hard Reset | Power cycle           | 5s off → 2s pause → 0.5s on |\n\nThe dashboard tracks real-time status, disables buttons when actions are in progress, and keeps polling the device state\nover the API so out-of-band power changes show up automatically.\n\n---\n\n## 🔧 Service management\n\n```bash\n# Check status\nsystemctl status panther-minor-controller\n\n# View logs\njournalctl -u panther-minor-controller -f\n\n# Restart\nsudo systemctl restart panther-minor-controller\n\n# Stop\nsudo systemctl stop panther-minor-controller\n\n# Enable on boot (default)\nsudo systemctl enable panther-minor-controller\n```\n\n### Environment variables\n\nEnv vars are set in `/opt/panther-minor-controller/env` and loaded by the `systemd` service.\n\n| Variable         | Description                                           | Default |\n| ---------------- | ----------------------------------------------------- | ------- |\n| `GPIO_PIN`       | BCM GPIO pin for the relay                            | `17`    |\n| `PORT`           | HTTP server port                                      | `8080`  |\n| `STATUS_POLL_MS` | Status polling interval for the backend and dashboard | `2000`  |\n| `STATUS_HOST`    | Hostname or IP address to probe over TCP              | —       |\n| `STATUS_PORT`    | TCP port used for the reachability probe              | —       |\n\n---\n\n## 🛡️ Security\n\nThe controller is designed with a defense-in-depth approach:\n\n- **Tailscale only** — the server binds to `0.0.0.0` but is only reachable through your Tailscale network\n- **Hardened SSH** — custom port, key-only authentication, no root login\n- **UFW firewall** — only SSH port is open; all other inbound traffic is denied\n- **fail2ban** — protects against SSH brute-force attempts\n\n---\n\n## 📚 More documentation\n\n- [API Reference](API.md) — details of the REST API endpoints and expected responses\n- [WOL Setup](WOL.md) — how to set up Wake-on-LAN for remote wake/sleep control (advanced)\n- [Panther Minor](https://github.com/rozsival/panther-minor) — the AI workstation this controller manages\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frozsival%2Fpanther-minor-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frozsival%2Fpanther-minor-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frozsival%2Fpanther-minor-controller/lists"}