{"id":27644713,"url":"https://github.com/bleedingxiko/ghosthub","last_synced_at":"2026-04-26T02:02:40.037Z","repository":{"id":288807062,"uuid":"969231520","full_name":"BleedingXiko/GhostHub","owner":"BleedingXiko","description":"A real-time media browser with chat, view sync, and optional tunnel sharing — all in a single .exe.","archived":false,"fork":false,"pushed_at":"2025-04-23T04:44:30.000Z","size":19186,"stargazers_count":73,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-24T00:58:28.183Z","etag":null,"topics":["cloudflare-tunnel","flask","local-server","media-server","no-database","open-source","privacy-first","pwa","python","realtime-chat","selfhosted","streaming","tiktok-style","websocket"],"latest_commit_sha":null,"homepage":"","language":"Python","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/BleedingXiko.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-19T17:26:12.000Z","updated_at":"2025-04-24T00:14:54.000Z","dependencies_parsed_at":"2025-04-19T20:18:50.606Z","dependency_job_id":"40c9a93e-f2dc-466a-91eb-ae11014f7e5d","html_url":"https://github.com/BleedingXiko/GhostHub","commit_stats":null,"previous_names":["bleedingxiko/ghosthub"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BleedingXiko%2FGhostHub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BleedingXiko%2FGhostHub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BleedingXiko%2FGhostHub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BleedingXiko%2FGhostHub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BleedingXiko","download_url":"https://codeload.github.com/BleedingXiko/GhostHub/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250540999,"owners_count":21447427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cloudflare-tunnel","flask","local-server","media-server","no-database","open-source","privacy-first","pwa","python","realtime-chat","selfhosted","streaming","tiktok-style","websocket"],"created_at":"2025-04-24T00:58:33.876Z","updated_at":"2026-04-26T02:02:40.031Z","avatar_url":"https://github.com/BleedingXiko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GhostHub\n\n**A private Raspberry Pi 4 media hub that feels like a polished streaming app, runs from your own storage, and works without a cloud account.**\n\nGhostHub turns a Raspberry Pi 4 into a local-first photo and video system for USB drives, phones, tablets, laptops, and an HDMI screen. It gives you a cinematic browser UI, profiles, uploads, resume progress, TV casting, admin controls, offline access-point mode, and GitHub Releases updates in a package you can inspect and modify.\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/BleedingXiko/GhostHub/releases/latest\"\u003e\u003cstrong\u003eLatest Release\u003c/strong\u003e\u003c/a\u003e\n  · \u003ca href=\"docs/QUICK_START.md\"\u003e\u003cstrong\u003eQuick Start\u003c/strong\u003e\u003c/a\u003e\n  · \u003ca href=\"docs/FLASH_GHOSTHUB_IMAGE.md\"\u003e\u003cstrong\u003eFlash Image\u003c/strong\u003e\u003c/a\u003e\n  · \u003ca href=\"docs/DIY_INSTALL.md\"\u003e\u003cstrong\u003eDIY Install\u003c/strong\u003e\u003c/a\u003e\n  · \u003ca href=\"CONTRIBUTING.md\"\u003e\u003cstrong\u003eContributing\u003c/strong\u003e\u003c/a\u003e\n  · \u003ca href=\"SECURITY.md\"\u003e\u003cstrong\u003eSecurity\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"StreamingLayout.PNG\" alt=\"GhostHub streaming layout on mobile\" width=\"31%\"\u003e\n  \u003cimg src=\"WhosWatching.PNG\" alt=\"GhostHub profile picker on mobile\" width=\"31%\"\u003e\n  \u003cimg src=\"Settings.PNG\" alt=\"GhostHub system settings on mobile\" width=\"31%\"\u003e\n\u003c/p\u003e\n\n\u003e **Compatibility:** GhostHub's Pi install path is built for Raspberry Pi 4 on `2022-01-28-raspios-bullseye-armhf-lite`. It is not a generic \"any Raspberry Pi OS image\" installer.\n\n## Why GhostHub\n\n- **Your media stays yours.** Browse local USB storage from any browser on your network.\n- **Built for the couch and the pocket.** Mobile-first UI, HDMI kiosk mode, and TV casting are first-class.\n- **Useful offline.** The Pi can create its own `GhostHub` Wi-Fi network for portable setups.\n- **Not just a demo.** Uploads, downloads, profiles, progress, themes, admin tools, logs, updates, and hardware status are included.\n- **Open source and hackable.** Python 3.9 backend, modular ES frontend, SPECTER services/controllers, and vendored RAGOT runtime.\n\n## 30-Second Setup\n\n### Fastest: Flash The Ready-To-Use Image\n\n1. Download the ready-to-flash GhostHub image from the project download page or announcement post.\n2. Flash it to a microSD card with Raspberry Pi Imager or balenaEtcher.\n3. Boot the Pi, connect to the `GhostHub` Wi-Fi network, and open `http://ghosthub.local` or `http://192.168.4.1`.\n\nThat path is meant for a fresh Raspberry Pi 4 and gets you to a working GhostHub without cloning the repo.\n\n### DIY: Install On The Supported Raspberry Pi OS Image\n\nUse the exact supported base OS:\n\n```text\n2022-01-28-raspios-bullseye-armhf-lite\n```\n\nDownload the trusted clean OS image from Raspberry Pi:\n\n```text\nhttps://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2022-01-28/2022-01-28-raspios-bullseye-armhf-lite.zip\n```\n\nUse Raspberry Pi Imager v1.8.5 and open advanced options before flashing:\n\n```text\nHostname: ghosthub\nUsername: ghost\nEnable SSH: yes\nPassword: choose your own\nWi-Fi: optional, only needed if you are not using Ethernet\n```\n\nFor the release installer path, SSH into the Pi and run:\n\n```bash\nssh ghost@ghosthub.local\n```\n\n```bash\ncurl -L -o install_ghosthub.sh \\\n  https://github.com/BleedingXiko/GhostHub/releases/latest/download/install_ghosthub.sh\nchmod +x install_ghosthub.sh\nsudo ./install_ghosthub.sh\n```\n\nThe installer downloads `Ghosthub_pi_github.zip` from GitHub Releases, installs system dependencies, configures the service, prepares USB/AP/HDMI support, and starts GhostHub.\n\nIf you cloned this repository and want to deploy local source instead, do not SSH into the Pi. Run the deploy CLI from your computer:\n\n```bash\n./scripts/deploy_to_pi.sh\n```\n\nThe CLI offers Standard, Update, and Image Prep modes. It creates `venv/`, installs Python and JavaScript dependencies, builds the local `ghostpack` ZIP, uploads it from your computer, and never downloads app ZIPs from GitHub Releases.\n\n## What You Get\n\n- Browser-based photo and video browsing from USB drives or configured media folders.\n- Mobile, tablet, desktop, and HDMI kiosk experiences.\n- Upload, download, rename, delete, move, and organize media.\n- Gallery, streaming, and default browsing layouts.\n- Category discovery, hidden folders, playlists, sorting, search, and progress tracking.\n- Video playback with subtitles, thumbnails, resume progress, and browser-native controls.\n- TV casting to an HDMI display connected to the Pi.\n- Raspberry Pi access-point mode for offline use.\n- Optional remote access experiments with tunnels or secure mesh.\n- Admin tools for updates, storage, Wi-Fi, cache, restart, logs, and system status.\n\n## How GhostHub Runs\n\nGhostHub is a Python 3.9 + Flask/SPECTER backend with a modular ES frontend. It is packaged for Raspberry Pi but stays hackable as a normal source tree.\n\n```text\nRaspberry Pi 4 + USB storage\n        |\n        v\nGhostHub service on port 5000\n        |\n        +-- phone/tablet/desktop browser\n        +-- HDMI kiosk / TV display\n        +-- optional mesh or tunnel access\n```\n\n## Install Options\n\n### Base Image\n\nUse this when you want the fastest path from blank SD card to working GhostHub.\n\nSee [Flash The GhostHub Image](docs/FLASH_GHOSTHUB_IMAGE.md).\n\n### Release Installer\n\nUse this when the exact supported Raspberry Pi OS image is already installed:\n\n```text\n2022-01-28-raspios-bullseye-armhf-lite\n```\n\n```bash\nsudo ./install_ghosthub.sh --version v5.0.1\n```\n\nInstall from a local release ZIP:\n\n```bash\nsudo ./install_ghosthub.sh --local-zip /path/to/Ghosthub_pi_github.zip\n```\n\nCompatibility local deploy mode still reads `/tmp/ghosthub_deploy.zip`:\n\n```bash\nsudo ./install_ghosthub.sh --local-only\n```\n\nSee [Quick Start](docs/QUICK_START.md).\n\n## Updates\n\nGhostHub updates are published through [GitHub Releases](https://github.com/BleedingXiko/GhostHub/releases). The admin UI checks the latest `vX.Y.Z` tag, downloads the release installer, validates it, and schedules the update through `systemd-run`.\n\nRuntime state is preserved during updates:\n\n- `instance/`\n- `venv/`\n- `headscale`\n- `cloudflared`\n\nPublic release assets are:\n\n- `Ghosthub_pi_github.zip`\n- `install_ghosthub.sh`\n\nThe ready-to-flash GhostHub SD card image is published separately by the maintainer. It is not produced by `scripts/ghostpack.py` and is not attached by the GitHub release workflow.\n\nSee [Release Process](docs/RELEASES.md).\n\n## Development\n\nGhostHub targets Python 3.9. Use a Python 3.9 virtual environment so local tests match Raspberry Pi deployments.\n\n```bash\npython3.9 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\ncd static/js\nnpm install\ncd ../..\npython ghosthub.py\n```\n\nRun validation:\n\n```bash\n./venv/bin/python scripts/run_all_tests.py\n```\n\nRun focused backend/frontend tests:\n\n```bash\n./venv/bin/python -m pytest tests/test_admin_routes.py -v\ncd static/js \u0026\u0026 npm test\n```\n\n## Architecture\n\n- Backend routes and services use the `specter-runtime` package.\n- Frontend modules use the vendored RAGOT runtime at `static/js/libs/ragot.esm.min.js`.\n- SQLite stores app state in `instance/`.\n- Raspberry Pi service setup is handled by `install_ghosthub.sh`.\n- Release ZIPs are built with `scripts/ghostpack.py --zip`.\n\nStart with [Architecture](docs/ARCHITECTURE.md) if you are changing internals.\n\n## Documentation\n\n- [Quick Start](docs/QUICK_START.md)\n- [Docs Index](docs/README.md)\n- [Flash The GhostHub Image](docs/FLASH_GHOSTHUB_IMAGE.md)\n- [DIY Install](docs/DIY_INSTALL.md)\n- [User Guide](docs/HOW_TO_USE_GHOSTHUB.md)\n- [Contributing](CONTRIBUTING.md)\n- [Release Process](docs/RELEASES.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Manual QA](docs/MANUAL_QA_CHECKLIST.md)\n- [Secure Mesh Quick Start](docs/MESH_QUICK_START.md)\n- [Secure Mesh Troubleshooting](docs/SECURE_MESH_TROUBLESHOOTING.md)\n- [Design Language](docs/DESIGN_LANGUAGE.md)\n- [Third-Party Licenses](docs/THIRD_PARTY_LICENSES.md)\n- [Security Policy](SECURITY.md)\n\n## Contributing\n\nIssues, fixes, docs, tests, Raspberry Pi validation, and release-readiness improvements are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening larger changes.\n\nFor backend work, follow the existing SPECTER controller/service patterns. For frontend work, use the existing ES module structure and RAGOT runtime.\n\n## Security\n\nPlease do not post credentials, private media libraries, device logs with secrets, or private network details in public issues. See [SECURITY.md](SECURITY.md).\n\n## License\n\nNew GhostHub source code is licensed under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE).\n\nOlder public GhostHub releases may remain available under the MIT License; this repository's current source tree is AGPL-3.0.\n\n## Donations\n\nIf GhostHub is useful to you, donations and sponsorships help support Raspberry Pi test hardware, maintenance time, and release infrastructure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbleedingxiko%2Fghosthub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbleedingxiko%2Fghosthub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbleedingxiko%2Fghosthub/lists"}