Frequently Asked Questions¶

Common questions about Peek Stash Browser.

General¶

What is Peek?¶

Peek is a modern web application for browsing and streaming your Stash media library. It provides a mobile-friendly interface with multi-user support, playlists, recommendations, and watch history.

How is Peek different from Stash?¶

Peek is a browser/player focused on video playback and discovery, while Stash is a comprehensive media organizer. Peek:

Provides a mobile-friendly, browsing-focused interface
Supports multiple users with separate preferences and restrictions
Includes playlists, recommendations, and watch history
Proxies video streams through Stash (no local media access needed)
Complements Stash rather than replacing it

Does Peek modify my Stash library?¶

Peek never edits your files or your Stash metadata (titles, tags, performers and the like). The one thing it writes to Stash is a user's own activity, and only when an admin switches Sync to Stash on for that user: ratings (not on tags), favorites (performers, studios and tags), plays, watch time, resume points and O counts. Admins switch it on per user under Settings → Server Settings → User Management. See Sync to Stash.

How does Peek sync with Stash?¶

Peek maintains a local cache of your Stash library for fast queries. Two kinds of sync keep it updated:

Scheduled sync (automatic) - Runs on startup and then every sync interval (every hour by default, set under Settings → Server Settings → Server Configuration), only syncing what changed
Full Sync - Complete refresh, from the Full Sync button under Server Statistics, and automatically once a day (the startup or a scheduled sync becomes a full one) to catch changes Stash makes without marking items updated. When an upgrade changes how Peek stores part of the library, the next sync refetches that part whole on its own

Key points:

Syncing happens in the background - you can browse while it runs
Large libraries (100k+ scenes) may take several minutes for full sync
Changes made in Stash appear in Peek after the next sync
Open pages pick up a finished sync on their next request; you don't need to reload
User data (watch history, playlists, ratings) is stored separately and never affected by sync
The library sync only reads from Stash. Your own activity goes to Stash only through Sync to Stash, and an admin can bring a user's activity in from Stash with Sync from Stash, both in Settings → Server Settings → User Management

See Sync Architecture for technical details.

Installation¶

What platforms are supported?¶

unRAID: Manual Docker template installation
Docker: Any platform supporting Docker (AMD64 and ARM64)
Development: Node.js 22 on Windows/Mac/Linux

Do I need a separate database server?¶

No. Peek uses embedded SQLite. No PostgreSQL, MySQL, or other database server needed.

Can I run Peek and Stash on the same server?¶

Yes, and this is recommended for best performance. They run as separate containers and don't conflict.

Video Playback¶

How does video streaming work?¶

Peek proxies video streams directly through Stash. When you play a video in Peek, it fetches the stream from Stash's API and delivers it to your browser. This means:

No local media access or path mapping needed
Uses Stash's transcoding capabilities
Quality options come from Stash

Why are videos loading slowly?¶

Since Peek proxies streams from Stash, performance depends on:

Network speed between Peek and Stash (same machine/LAN is best)
Stash server's transcoding performance
Your browser's network connection

If videos are slow in Peek, check if they're also slow in Stash directly.

Configuration¶

Where are my settings stored?¶

User data: SQLite database in /app/data/peek-stash-browser.db
Server config: Environment variables
Stash connection: Stored in database (configured via Setup Wizard)

How do I backup my data?¶

See Upgrading - Backup Procedure for detailed instructions.

Can I customize the theme?¶

Yes! Peek includes built-in themes (Peek, Light, Midnight Blue, Deep Purple, The Hub) and a custom theme editor where you can create your own color schemes. Pick one under Settings → User Preferences → Theme.

Your theme follows your account: it is saved with your settings, so every browser you sign in on shows it. If a saved theme is missing (a custom theme that was deleted, or another user's custom theme on a shared browser), Peek shows the default Peek theme instead.

Features¶

How do playlists work?¶

Create custom playlists of your favorite scenes:

Click Playlists in the navigation
Click Create Playlist
Add scenes with the Add to Playlist button on a scene's page or player, or select scenes in a list and use Add to Playlist on the bar that appears

See the Playlists Guide for details.

Does Peek track watch history?¶

Yes! Peek automatically tracks your viewing progress and lets you resume playback. Features include:

Automatic progress tracking
Resume from any device
"Continue Watching" section
Progress bars on scene cards

See the Watch History Guide for details.

Yes! Peek supports keyboard navigation including arrow keys, Enter to select, and video player shortcuts.

See the Keyboard Navigation Guide for all shortcuts.

What about TV Mode?¶

TV Mode is for couch and remote browsing. Turn it on from the user menu. The arrow keys then move focus to the nearest item in that direction, on every page, and Enter opens it. The best experience is with a wireless keyboard.

See TV Mode for the details.

Can I use Peek on mobile?¶

Yes. The web interface is responsive and works on mobile browsers.

Can I use Peek without Stash?¶

No. Peek requires a Stash server for media library management and streaming.

Security¶

Is Peek secure?¶

Peek includes JWT authentication, bcrypt password hashing, and session management.

There is no default password. The setup wizard asks you to choose the admin account's password, so pick a strong one.

Should I expose Peek to the internet?¶

Not recommended without additional protection. For remote access:

Use a VPN
Use a reverse proxy with authentication (see Proxy Authentication)
Don't expose directly to the internet

Support¶

Where can I get help?¶

How do I report a bug?¶

Check the Troubleshooting Guide first
Search existing issues
Create a new issue with: Peek version, Stash version, logs, and steps to reproduce