---
title: "PeakCut on Docker: Self-Hosted AI Video Clipper (BYOK)"
description: "Self-host PeakCut with Docker Compose to turn long videos and livestreams into captioned 9:16 clips using local transcription and your own AI API key."
date: 2026-11-20
categories: ["ai"]
tags: ["self-hosted","docker","video"]
---

If you publish YouTube tutorials, podcasts, or Twitch/Kick streams, you already know the SaaS clipping tax. Tools like OpusClip or Vizard charge monthly seat fees, cap processing minutes, stamp watermarks on lower tiers, and require uploading multi-gigabyte raw recordings to someone else's cloud before you even see whether the cuts are usable.

[PeakCut](https://github.com/haziqahmedqasmi/PeakCut) (MIT license, 1,400+ GitHub stars in its first week in November 2026) takes a different approach: run the clipping pipeline on your own computer or Linux server, transcribe audio locally with `sherpa-onnx` (Parakeet), and send only the text transcript to your own AI key (Gemini, OpenAI, Claude, Groq, OpenRouter, xAI, or local Ollama) to pick the best moments and write hooks.

Here is how PeakCut works under the hood, how to deploy it on a laptop or Docker server, what it actually costs per hour of video, and where a self-hosted clipper falls short of paid SaaS tools.

## How PeakCut works (and why the architecture is smart)

PeakCut is a FastAPI Python backend paired with plain HTML/CSS/JS pages (no heavy frontend build step), `ffmpeg`, and `yt-dlp`. When you paste a YouTube, Twitch, or Kick link (or upload a local MP4):

1. **Audio stays on your hardware.** Speech-to-text runs locally using `sherpa-onnx` and the Parakeet model (~480 MB downloaded once on first run), or uses YouTube's existing transcript when `PEAKCUT_YT_TRANSCRIPT=1`. Raw video and audio never leave your box.
2. **Only text hits the LLM.** A fast model reads the transcript (PeakCut's docs note a one-hour video takes about four LLM requests) and returns JSON timestamps, hooks, and titles. If you omit an AI key completely, PeakCut still cuts clips using audio loudness peaks alone.
3. **`ffmpeg` renders 9:16 vertical clips** with word-by-word burned-in captions in three built-in styles, and for live streams it records into a rolling buffer and clips highlights mid-stream using loudness, chat activity, and transcript cues.
4. **Built-in backpressure.** Every second, the server checks CPU, free RAM, and disk space (`PEAKCUT_BUSY_CPU=82`, `PEAKCUT_MIN_FREE_RAM_GB=1.5`) so extra jobs wait in per-user queues instead of crashing a shared VPS.

## Self-hosted PeakCut vs SaaS clippers

| Dimension | PeakCut (Self-Hosted) | Hosted SaaS (OpusClip, Vizard, etc.) |
|---|---|---|
| Software cost | **Free (MIT)** | ~$15–$40+/month depending on minutes |
| Per-hour video cost | Pennies in LLM text tokens (or $0 with Ollama) | Included up to monthly minute cap |
| Raw footage privacy | Stays on your disk; local `sherpa-onnx` ASR | Uploaded to vendor cloud |
| Live stream clipping | Rolling buffer + loudness/chat/transcript triggers | Rare or enterprise-tier only |
| Caption polish & B-roll | 3 clean word-by-word styles; no stock B-roll | Dozens of animated templates, auto B-roll, reframing |
| Multi-platform posting | YouTube, Instagram, TikTok (requires your own OAuth apps) | One-click OAuth managed by the SaaS |
| Hardware needed | Any modern laptop or 2–4 vCPU VPS (optional GPU node for ASR) | None (runs in browser) |

That comparison makes the trade-off obvious. If you want fancy animated templates, AI face-tracking reframing, and zero OAuth setup for TikTok/Instagram, a paid SaaS still wins on polish. If you sit on hours of technical streams, conference talks, or coding sessions and just want clean vertical clips without monthly minute caps, PeakCut beats paying $30/month easily. (For scripted, code-rendered videos from scratch rather than cutting existing footage, see my [HyperFrames Studio review](/hyperframes-studio-review/) or [Python video intro editor guide](/python-video-intro-editor/).)

## Install PeakCut: local laptop vs Docker server

### Docker Compose (VPS / Homelab)

PeakCut ships an official `docker-compose.yml` running three services: `postgres:16-alpine`, the FastAPI `app` bound to `127.0.0.1:8765`, and an optional Caddy container (`COMPOSE_PROFILES=own-https`) for automatic HTTPS.

Clone the repo and configure `.env`:

```bash
git clone https://github.com/haziqahmedqasmi/PeakCut.git ~/peakcut
cd ~/peakcut
cp .env.example .env
```

Edit `.env` with your domain, Postgres password, AI provider, and safety caps (important if you share the VPS with other containers):

```env
PEAKCUT_DOMAIN=peakcut.example.com
POSTGRES_PASSWORD=replace-with-long-random-password

# Bring your own AI key (or leave blank and set in Settings -> AI)
PEAKCUT_AI_PROVIDER=gemini
PEAKCUT_AI_MODELS=gemini-2.5-flash
PEAKCUT_AI_KEY=your-api-key-here

# Required on any reachable server so strangers cannot spend your AI key
PEAKCUT_ACCOUNTS=1

# Uncomment if PeakCut owns ports 80/443 on this box (skip if using Traefik/Nginx)
COMPOSE_PROFILES=own-https

# Resource guardrails for a shared server
PEAKCUT_MEM_LIMIT=4g
PEAKCUT_CPUS=2
PEAKCUT_CPU_SHARES=512
PEAKCUT_OOM_SCORE_ADJ=900
PEAKCUT_DB_MEM_LIMIT=256m
```

Build and start the stack:

```bash
docker compose up -d --build
```

Sign up for your account in the browser, then promote yourself to admin from the CLI (PeakCut refuses to grant admin roles through the web UI):

```bash
docker compose exec app python -m studio.admin grant you@example.com
```

If you already run [Traefik](/traefik-proxy-docker/) on the same host, omit `COMPOSE_PROFILES=own-https` and combine PeakCut's bundled Traefik override instead (`COMPOSE_FILE=docker-compose.yml:deploy/docker-compose.traefik.yml`).

### Local Mac / Linux / Windows

On your own workstation, you do not need Postgres or accounts. SQLite stores everything in `./data`, and the dashboard opens straight up with no login screen. Install Python 3.10+ and `ffmpeg` first (`brew install ffmpeg` on macOS, `sudo apt install ffmpeg` on Ubuntu/Debian, `winget install Gyan.FFmpeg` on Windows).

```bash
git clone https://github.com/haziqahmedqasmi/PeakCut.git ~/peakcut
cd ~/peakcut
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m studio.server
```

On Windows, clone to a short path like `C:\peakcut` so the speech model does not hit Windows' 260-character file path limit.

First startup downloads the ~480 MB Parakeet speech model once. Open `http://127.0.0.1:8765`, go to **Settings -> AI**, pick your provider (or `ollama` for 100% offline local models), click **Save and test**, and paste your first video URL.

## Choosing the right AI model (and running 100% local with Ollama)

You do not need a frontier reasoning model to scan a transcript for strong hooks. PeakCut only needs a fast JSON-capable chat model:

- **Best cheap API choice:** Gemini Flash (`PEAKCUT_AI_PROVIDER=gemini`) or Groq (`llama-3.3-70b-versatile`). A full one-hour video takes roughly four requests, costing a fraction of a cent. You can also put comma-separated model IDs in `PEAKCUT_AI_MODELS` so the second acts as an automatic fallback.
- **100% local / zero API bill:** Set `PEAKCUT_AI_PROVIDER=ollama` and point it at a local model (like `llama3.1` or `qwen3` running on your [Ollama Docker setup](/ollama-docker-install/)). Quality depends heavily on how well the local model follows structured JSON output; check the **AI usage** page inside PeakCut to spot parse retries.
- **Offloading transcription to a GPU machine:** CPU transcription via `sherpa-onnx` works fine for occasional videos, yet if you process multi-hour VODs daily, PeakCut supports a separate GPU ASR worker (`deploy/gpu/docker-compose.yml`) wired via `PEAKCUT_ASR_URL` and `PEAKCUT_ASR_TOKEN`.

**Never expose PeakCut without PEAKCUT_ACCOUNTS=1**

On a local laptop, PeakCut disables authentication by default for convenience. On any public server or reverse proxy, keep `PEAKCUT_ACCOUNTS=1` (the Docker Compose file enforces this by default) and store keys via `PEAKCUT_AI_KEY_FILE=/secrets/ai.txt` or [Docker Compose secrets](/docker-compose-secrets/). Otherwise anyone who discovers your subdomain can burn through your API credits and disk space.

## Things to know before putting PeakCut on a small VPS

- Disk space fills up fast with raw VODs. PeakCut monitors free disk and pauses new jobs before filling the drive, so mount /data on a large volume (or move storage from Settings -&gt; Storage) and set PEAKCUT_MAX_USER_GB if friends share the instance.

- Cloudflare upload limits. If you proxy through Cloudflare's orange cloud, keep PEAKCUT_UPLOAD_PART_MB=40 (chunked uploads stay under Cloudflare's 100 MB request cap) and set PEAKCUT_CLIENT_IP_HEADER=CF-Connecting-IP.

- Auto-posting takes one-time OAuth setup. Generating and downloading MP4 clips works in five minutes; auto-posting directly to YouTube Shorts, Instagram, or TikTok requires creating your own OAuth apps (documented in DEPLOY.md).

- Updates are straightforward. PeakCut checks GitHub commit hashes for newer builds (disable with PEAKCUT_UPDATE_CHECK=0 if you want zero outbound checks) and updates with git pull &amp;&amp; docker compose up -d --build without touching .env or clips.

## Bottom line

PeakCut is one of the cleaner self-hosted AI tools to land on GitHub recently: MIT licensed, sensible CPU/RAM backpressure, local speech recognition, and no forced cloud account. Start with the local Python run on one of your existing 30-minute YouTube videos using a cheap Flash model or Ollama, check whether the clip boundaries and captions match your bar, and only then bother deploying the Docker + Postgres stack on a VPS.

## FAQ

**Does PeakCut need a GPU to run?**

No. Audio transcription runs on CPU via `sherpa-onnx` (Parakeet) and clip rendering uses standard `ffmpeg`. A GPU is completely optional and only speeds up heavy batch workloads via the separate GPU ASR compose profile (`PEAKCUT_ASR_URL`).

**Can PeakCut run without any AI API key?**

Yes. Without an AI key configured, PeakCut falls back to cutting clips by audio loudness peaks alone, though you lose AI-generated titles, hooks, and semantic moment selection. Alternatively, connect it to a local Ollama instance for $0 API cost.

**Why does PeakCut's Docker Compose use PostgreSQL while local install uses SQLite?**

On a single-user workstation, SQLite inside `./data` keeps setup to one Python process. On a multi-user server with concurrent uploads, live recordings, and per-user job queues, PostgreSQL handles concurrent writes cleanly without SQLite lock contention.

**How much does it cost in API tokens to clip a 1-hour video?**

Because audio transcription runs locally on your machine, you only pay for text tokens on the transcript. PeakCut reads a 1-hour video in roughly four LLM requests, which costs well under a penny on models like Gemini Flash or Groq, or $0 with Ollama.