PeakCut on Docker: Self-Hosted AI Video Clipper (BYOK)
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.
7 min read

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 (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):
- Audio stays on your hardware. Speech-to-text runs locally using
sherpa-onnxand the Parakeet model (~480 MB downloaded once on first run), or uses YouTube’s existing transcript whenPEAKCUT_YT_TRANSCRIPT=1. Raw video and audio never leave your box. - 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.
ffmpegrenders 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.- 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 or Python video intro editor guide.)
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:
git clone https://github.com/haziqahmedqasmi/PeakCut.git ~/peakcut
cd ~/peakcut
cp .env.example .envEdit .env with your domain, Postgres password, AI provider, and safety caps (important if you share the VPS with other containers):
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=256mBuild and start the stack:
docker compose up -d --buildSign 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):
docker compose exec app python -m studio.admin grant [email protected]If you already run Traefik 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).
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.serverOn 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 inPEAKCUT_AI_MODELSso the second acts as an automatic fallback. - 100% local / zero API bill: Set
PEAKCUT_AI_PROVIDER=ollamaand point it at a local model (likellama3.1orqwen3running on your Ollama Docker setup). 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-onnxworks 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 viaPEAKCUT_ASR_URLandPEAKCUT_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. 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
/dataon a large volume (or move storage from Settings -> Storage) and setPEAKCUT_MAX_USER_GBif 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 setPEAKCUT_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=0if you want zero outbound checks) and updates withgit pull && docker compose up -d –buildwithout touching.envor 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.
Did this guide work for you?
Need help with Astro, VPS, or a self-hosted app? View services →


