How to Use GhostHub OasiS
Complete guide to GhostHub OasiS 3.0 - your personal media hub.
Quick Start
Get GhostHub running in under 5 minutes. This is all you need to start watching your media.
What you need
- • GhostHub OasiS device (Raspberry Pi with GhostHub OasiS 3.0)
- • USB drive with your photos/videos
- • Phone, tablet, or computer with WiFi
What GhostHub OasiS does
Your personal media hub. Watch anywhere with three viewing modes, TV casting, watch parties, and secure remote access.
Get Started in 5 Steps
- 1Plug in your USB drive with photos/videos into the GhostHub device
- 2Connect to WiFi: Join the "GhostHub" networkPassword: ghost123⚠️ Change this in Settings for security
- 3Open browser and go to
http://192.168.4.1orhttp://ghosthub.local - 4Browse categories — tap any folder to start viewing
- 5Swipe up/down to move between photos and videos
Basic Controls
On phone/tablet
- • Swipe up = next item
- • Swipe down = previous item
- • Swipe right = back to categories
- • Tap = play/pause videos
On computer
- • Arrow down = next item
- • Arrow up = previous item
- • Click back arrow = return to categories
- • Click = play/pause videos
Who This Is For
Perfect for
- • Families sharing photos/videos at home or remotely
- • Privacy-conscious users who want local-first media
- • Remote streaming via secure tunnels (no port forwarding)
- • Small gatherings and watch parties
- • Anyone who wants "plug and play" media
Not for
- • Users expecting fully-managed, always-on cloud hosting
- • Large organizations needing multi-user accounts
- • People who want to edit/delete files from the UI
- • Users requiring built-in transcoding (use GhostStream instead)
- • Those who need granular user permissions
Everyday Features
These are the features you'll use most often for watching and sharing media.
Browsing Your Media
GhostHub shows your USB folders as "categories" on the home screen.
Category cards show:
- • Thumbnail preview of folder contents
- • Media count (e.g., "42" items)
- • Type icon: for videos, for photos
- • Progress bar if you're watching through a folder
Navigation tips
- Filter by All, Videos, or Photos at the top
- Use arrows to see if more items exist
- Double-tap for fullscreen on videos
Continue Watching
GhostHub remembers where you left off, like Netflix.
What you'll see:
- • Category badges show your position: "15/42"
- • Red progress bars on category cards
- • "Continue Watching" row in Streaming layout
Note: This needs to be enabled by the admin in Settings.
Sync Mode
Watch together with friends and family. Everyone sees the same thing at the same time.
How it works:
- First person to click "Sync" becomes the Host
- Host controls what everyone sees
- Guests automatically follow along
- Guests can't change items — just watch
Perfect for watch parties or showing photos to a group.
Casting to TV
Send media to your TV if your GhostHub is connected via HDMI (admin only).
To cast:
- Make sure TV is connected to GhostHub via HDMI
- Claim admin (click the lock icon)
- Browse to any media item
- Click the cast button in the header
Control playback from your phone — TV follows along.
Three Viewing Modes
GhostHub OasiS 3.0 includes three completely different ways to browse your media.
Default (TikTok Style)
Full-screen swipe interface. Perfect for browsing on your phone.
Streaming (Netflix Style)
Horizontal scrolling rows with continue watching. Great for movies.
Gallery (Photo Grid)
Photo grid organized by date. Ideal for photo libraries.
Built-in themes: Dark, Midnight, Nord, Monokai, Dracula. Plus custom theme builder.
Theme Builder (Custom Themes)
Create your own color themes:
- Open Settings → Themes & Layout → "Open Theme Builder"
- Choose a preset palette or customize individual colors (Primary, Secondary, Accent, Background, Surface, Text)
- Use Random for new palettes, or Invert to flip light/dark
- Preview in real-time, then click Save Theme
Custom themes appear in the dropdown with
Advanced / Admin
Power-user features, file management, and administrative controls.
File Management
Upload and download files to your USB drives (admin for uploads, anyone can download).
Upload methods:
- • Admin File Manager: Settings → File Manager (full control)
- • Gallery drag-and-drop: Desktop only, password protected
- • Chunked uploads: Large files upload in pieces for reliability
Supported formats: JPG, PNG, MP4, WebM, plus others. Up to 16GB per file.
Optional: Transcoding with GhostStream
GhostStream is a separate transcoding service that provides on-the-fly video transcoding with adaptive bitrate streaming.
How it works:
- • Download GhostStream from GitHub (Windows/Mac/Linux/Docker)
- • Run on any machine on your network (doesn't have to be the Pi)
- • GhostHub automatically discovers it via mDNS - no configuration needed
- • Provides adaptive bitrate (4K/1080p/720p/480p) with hardware acceleration
When to use GhostStream
Use GhostStream if you have videos in formats that don't play directly in browsers (like MKV, AVI, or high-bitrate 4K content). GhostStream transcodes on-the-fly so you can watch any video format on any device. Requires a separate PC/server with decent CPU/GPU.
Remote Access Overview
Access GhostHub from anywhere using one of three methods. Each has different privacy and convenience tradeoffs.
| Method | Best For | Privacy | Setup | Sharing |
|---|---|---|---|---|
| Headscale/Tailscale Mesh | Trusted users (family/friends) | Maximum (zero-trust) | Moderate (requires app) | Share preauth key |
| Cloudflare Tunnel | Quick public sharing | Medium (via Cloudflare) | Easy (one-click) | Share URL link |
| Pinggy | Alternative tunnel | Medium (via Pinggy) | Easy (requires token) | Share URL link |
Which should I choose?
- • Use Mesh if: Sharing with family/friends, privacy is critical, users can install Tailscale app
- • Use HTTP Tunnels if: Need quick browser-only access, sharing with non-technical users, privacy is less critical
Secure Mesh Networking (Headscale/Tailscale)
Zero-trust WireGuard mesh networking. Your media is accessed through encrypted peer-to-peer tunnels. No traffic goes through third-party servers.
Requirements:
- • GhostHub connected to home WiFi (not just AP mode)
- • Internet connection for mesh setup
- • Trusted users with Tailscale app installed
How to Share Access
- 1Start Mesh: Settings → Remote Access → "Start Secure Mesh"Starts Headscale server on GhostHub (takes 30-60 seconds)
- 2Share Instructions: Users see platform-specific setup steps in the tunnel modalDesktop users get a ready-to-copy command. Mobile users get app configuration steps.
- 3They Connect: Users follow the simple instructions shownInstall Tailscale, run the provided command or configure app settings, done
- 4Access GhostHub: They visit
ghosthub.mesh.local:5000Encrypted connection directly to your GhostHub
What users need:
- • Tailscale app installed (free, available for all platforms)
- • Follow the platform-specific instructions shown in the GhostHub tunnel settings
- • That's it - setup is automatic
How It Works
Headscale is an open-source Tailscale control server running on your GhostHub Pi. When users join the mesh, they form encrypted WireGuard tunnels directly to your Pi. Your media never leaves your network through third-party servers. DNS automatically resolves ghosthub.mesh.local to your Pi's mesh IP address.
HTTP Tunnels (Cloudflare / Pinggy)
HTTP tunnels create a public URL that routes traffic through a third-party service. Simpler than mesh but less private.
Requirements:
- • GhostHub connected to home WiFi (not just AP mode)
- • Internet connection for tunnel setup
Providers:
- • Cloudflare Tunnel: Free, pre-installed
- • Pinggy: Easy setup, requires token
Click the tunnel button () in the header to configure.
Privacy Note
HTTP tunnels route your traffic through the provider's servers (Cloudflare or Pinggy). While encrypted in transit, the provider can theoretically inspect traffic. Use mesh networking if you require maximum privacy.
WiFi Settings (Pi Only)
Configure the GhostHub WiFi network when running in Access Point mode.
What you can change:
- • Network Name (SSID): The name that appears when connecting (1-32 chars)
- • Password: WiFi password (8-63 characters)
- • Channel: WiFi channel 1-11 (default: 7)
- • Country Code: Two-letter code for regulatory compliance
Access via Settings → WiFi Settings. Changes require a brief WiFi restart — devices will need to reconnect.
Chat Commands
Type commands in chat for quick actions.
Everyone can use:
- •
/help— show all commands - •
/myview— share what you're viewing - •
/search query— find files - •
/add— add to session playlist - •
/play 10— auto-play (10s per image)
Admin only:
- •
/kick user_id— remove user - • Access Settings and File Manager
- • Cast to TV
- • Configure tunnels
Admin Features
First person to click the lock icon () becomes admin for the session.
Admin can:
- • Access Settings (themes, passwords, features)
- • Use File Manager for uploads/downloads
- • Cast media to TV
- • Set up remote tunnels
- • Kick users with
/kick - • Clear saved data and update GhostHub
Click the lock again to release admin role for others.
USB Hotplug
GhostHub automatically detects when you plug in or remove USB drives.
What happens:
- • Plug in: Drive is scanned, new categories appear
- • Remove: Categories become unavailable, progress is saved
- • Thumbnails: Generated in background (you'll see progress)
Drives mount to /media/pi/DRIVENAME automatically.
Reference
Quick reference for indicators, troubleshooting, and settings.
UI Indicators
| Indicator | Meaning |
|---|---|
| Contains videos | |
| Images only | |
| Generating thumbnails | |
| Video playback progress | |
| Previous/next items available | |
| Auto-play active | |
| Currently casting to TV | |
| "Sync Mode: HOST" | You're controlling sync |
| You are admin |
Quick Troubleshooting
Common issues
- • Media not showing: Check USB connection, refresh page
- • Videos won't play: Try different browser, check format (MP4 works best)
- • Sync not working: Check connection, refresh both devices
- • Cast button missing: Must be admin, TV must be connected via HDMI
Performance tips
- • Use USB drives instead of SD card for media
- • Large folders take time to index initially
- • Refresh page if things seem stuck
- • Very large files may buffer on slow networks
Key Settings (Admin)
Important settings
- • Session Password: Protect access with password
- • Save Current Index: Enable Continue Watching
- • Enable Session Progress: Let guests save their own progress
- • Enable Subtitles: Show subtitle tracks if available
Layout & themes
- • UI Layout: Default/Streaming/Gallery
- • Color Theme: 5 built-in + custom themes
- • Theme Builder: Create custom color themes
- • Feature toggles: Show/hide chat, indicators
WiFi Settings (Pi only)
- • Network Name/Password: Customize AP credentials
- • Channel/Country: WiFi channel and regulatory code
Final Tips
- • Try different layouts: Streaming for movies, Gallery for photos
- • USB is your friend: Keep media on USB drives for best performance
- • Share with /myview: Easy way to show someone a specific item
- • Build playlists: Use
/addfor watch parties - • Refresh if stuck: Most issues solved by refreshing the page
Happy browsing! 👻