Streamscope Deep Dive: How to Self‑Host a Reliable Live Twitch Stream Recorder (2026 Guide)

The Community Spark #

The r/selfhosted subreddit lit up last week when a user posted “Just got Streamscope working on my cheap VPS—finally a way to archive Twitch streams without third‑party services!” Within minutes the thread exploded with questions, tweaks, and success stories. The core problem? Twitch’s “download‑only‑after‑broadcast” policy pushes creators and archivists toward either expensive cloud services or fragile, script‑based hacks. Streamscope promises a live recorder that runs 24/7 on modest hardware, but the community quickly realized that “plug‑and‑play” is a myth—configuration, storage, and API limits are real obstacles.

If you’re reading this, you’re probably:

• A content creator who wants a personal backup of every broadcast.
• An archivist looking to preserve niche streams for research.
• A sysadmin curious about running a low‑cost, self‑hosted media service.

Below is the distilled wisdom from the Reddit thread, plus the technical roadmap that turned curiosity into a production‑grade deployment.

Synthesized Community Perspectives #

Consensus: Streamscope is doable on modest hardware, but production reliability hinges on three pillars—API compliance, storage planning, and video pipeline stability. The disagreements centered around the choice of database and video codec tweaks; both have solid arguments depending on scale.

Deep‑Dive Actionable Guide #

Below is a step‑by‑step tutorial that incorporates the community’s hard‑won lessons. The guide assumes a fresh Ubuntu 22.04 LTS VPS (or any Debian‑based distro) with sudo privileges.

1️⃣ Prerequisites #

Tip: If you’re on a low‑end droplet, stick with SQLite (bundled) to avoid the extra PostgreSQL overhead.

2️⃣ Install Docker & Docker Compose #

# Update & install prerequisites
sudo apt-get update && sudo apt-get install -y \
    ca-certificates curl gnupg lsb-release

# Add Docker’s official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the stable repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Compose plugin
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Verify
docker version
docker compose version

3️⃣ Create a Dedicated Storage Volume #

# Example using a separate disk /dev/vdb (adjust to your provider)
sudo mkfs.ext4 /dev/vdb
sudo mkdir -p /mnt/streamscope
sudo mount /dev/vdb /mnt/streamscope
# Persist across reboots
echo '/dev/vdb /mnt/streamscope ext4 defaults 0 2' | sudo tee -a /etc/fstab

Why? A dedicated mount point prevents the root filesystem from filling up, which would otherwise cause Docker to abort silently.

4️⃣ Pull the Official Streamscope Docker Image #

docker pull ghcr.io/streamscope/streamscope:latest

The image is built on Alpine 3.18, keeping it under 150 MB.

5️⃣ Configure Environment Variables #

Create a .env file in a safe location (e.g., /home/ubuntu/streamscope/.env):

# Twitch credentials – keep these secret!
TWITCH_CLIENT_ID=your_client_id
TWITCH_CLIENT_SECRET=your_client_secret
TWITCH_OAUTH_TOKEN=oauth:your_generated_token

# Recording settings
RECORDING_PATH=/recordings
MAX_CONCURRENT=3                # Max simultaneous streams
RESOLUTION=1080p                # Options: 720p, 1080p, 1440p
FRAMERATE=60                    # 30 or 60

# Database (choose ONE)
# SQLite (default, no extra vars)
# PostgreSQL example:
POSTGRES_HOST=postgres
POSTGRES_DB=streamscope
POSTGRES_USER=ss_user
POSTGRES_PASSWORD=strongpassword

6️⃣ Docker Compose Stack #

Create docker-compose.yml next to the .env file:

version: "3.9"

services:
  streamscope:
    image: ghcr.io/streamscope/streamscope:latest
    container_name: streamscope
    restart: unless-stopped
    env_file:
      - ./.env
    volumes:
      - /mnt/streamscope/recordings:${RECORDING_PATH}
      - ./config:/app/config   # optional custom config files
    depends_on:
      - postgres   # only if you enabled PostgreSQL

  # Optional PostgreSQL service
  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data

volumes:
  pg_data:

Note: If you stay with SQLite, simply delete the postgres service and the depends_on line.

7️⃣ Start the Stack #

docker compose up -d
docker compose logs -f streamscope   # watch startup messages

You should see something like:

2026-07-14T22:31:12.345Z INFO Starting Streamscope v2.1.0
2026-07-14T22:31:12.350Z INFO Authenticated with Twitch (rate limit: 30 req/min)
2026-07-14T22:31:12.360Z INFO Listening for channel updates…

8️⃣ Adding Channels to Record #

Streamscope ships with a simple REST API (exposed on port 8080). You can add a channel via curl:

curl -X POST http://localhost:8080/api/v1/channels \
  -H "Authorization: Bearer ${TWITCH_OAUTH_TOKEN}" \
  -d '{"login":"example_channel","quality":"1080p60"}'

Alternatively, edit config/channels.yaml (mounted at ./config) and reload:

channels:
  - login: example_channel
    quality: 1080p60
  - login: another_streamer
    quality: 720p30

Then restart:

docker compose restart streamscope

9️⃣ Handling Twitch API Rate Limits #

Streamscope includes built‑in back‑off, but the community recommends spreading channel checks across the minute. Add a small delay in config/settings.yaml:

api:
  request_interval_seconds: 2   # default is 1

For heavy multi‑channel setups (>20), consider creating multiple Twitch apps each with its own token and load‑balance them via api.tokens list.

🔟 Monitoring & Alerts #

• Healthcheck: Docker automatically polls /healthz.
• Prometheus Exporter: Enable METRICS_ENABLED=true in .env and scrape http://localhost:9090/metrics.
• Log Rotation: Add a logrotate config to avoid giant Docker logs.

/var/lib/docker/containers/*/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

Pros & Cons / Comparative Table #

Bottom line: If you need continuous, multi‑channel, live archiving with a web UI, Streamscope wins. For one‑off VOD downloads, Twitch Leecher remains the simplest.

The Verdict / Expert Advice #

Key takeaways:

1. Respect Twitch limits – token rotation & request spacing are non‑negotiable.
2. Separate storage – bind‑mount a dedicated volume, prune old files automatically.
3. Monitor – Prometheus + Grafana dashboards give early