How to Self-Host OpenShorts with Docker

What you need before you start

• Docker and Docker Compose: use a Docker environment on Linux or macOS. On Windows, use Docker Desktop with its WSL2 backend and run the commands below in your WSL2 terminal.
• Memory and CPU: at least 8 GB of RAM and a modern multicore CPU.
• A Google Gemini API key: the free allowance described for this setup is 1,500 requests per day. A local LLM can replace Gemini, as explained below.
• Optional NVIDIA GPU: an RTX 4060-class GPU with 8 GB of video memory is the suggested hardware level for the GPU setup.

The first startup downloads transcription and scene-detection models. Allow that initial download to finish before treating a slow startup as a failure.

Self-host OpenShorts in four commands

Run these commands in order. They download the project, create your local environment file, and build and start the Docker Compose services.

git clone https://github.com/mutonby/openshorts.git
cd openshorts
cp .env.example .env
docker compose up --build

Keep the terminal available while the initial build and model downloads finish. The source project is available in the OpenShorts GitHub repository.

Open the app and add your API key

Open http://localhost:5175 in your browser. Go to Settings and paste your Gemini API key there. The backend API runs on port 8000.

Gemini supports the standard setup. The other integrations are optional; you do not need to configure every service to start clipping.

Turn on GPU acceleration (optional)

The reference timings for this setup are 5–8 minutes on CPU for an eight-minute source video, or about one minute with GPU acceleration. Treat these as approximate expectations, not measurements made by Clip Comparison or a promise for your hardware.

1. Add the Docker Compose override

Create docker-compose.override.yml beside the project's Compose file. Add the backend GPU build argument and NVIDIA device reservation:

services:
  backend:
    build:
      args:
        GPU: "1"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, video]

2. Set the GPU options in .env

Set these values in your .env file, then rebuild and start the services with docker compose up --build.

WHISPER_MODEL=large-v3-turbo
WHISPER_DEVICE=cuda
WHISPER_COMPUTE=float16
FFMPEG_ENCODER=auto

FFMPEG_ENCODER=auto detects NVENC and falls back to x264 if NVENC is unavailable. If transcription encounters a CUDA error, it retries once on CPU. Those fallback paths can make a misconfigured GPU setup slower rather than preventing the job from running.

Run it without a Google key

Set LLM_BASE_URL and LLM_MODEL in .env to the endpoint and model name of an OpenAI-compatible service. Supported choices for this approach include Ollama, LM Studio, vLLM, and llama.cpp.

Use a model with at least a 16k context window and roughly 7–8 billion parameters or more. A 3B model is not a reliable choice for the structured JSON needed by this workflow.

There are functional tradeoffs: automatic layout selection falls back to ordinary face-tracking crops, and videos without speech cannot produce clips through this local highlight-selection workflow.

An OpenAI-compatible endpoint is not necessarily local. To keep the LLM step on your machine, point these settings to a service running on your own hardware.

What stays on your machine

Your video files stay on the machine running OpenShorts. Downloading, transcription, scene detection, face tracking, reframing, and encoding run locally, and the resulting clips are written to your disk.

With Gemini enabled, the transcript text goes to Gemini. Automatic layout selection can also send a small selection of still frames. This is different from uploading the full video, but it is still an external transfer of content.

With a locally hosted LLM replacing Gemini, that analysis stays local too. This local-only description assumes you do not enable optional external services such as dubbing, AI video generation, or direct social publishing; those integrations involve their respective providers.

Self-hosted vs OpenShorts Cloud

The choice is between operating the software yourself and using the hosted service. The cloud timings and plan details below are reference figures, not results from our own comparative testing.

Self-hosting fits sensitive recording archives, higher volumes, or long source material, with local LLM processing when external transfers are unsuitable. Cloud fits a workflow that prioritizes roughly one-minute processing from any laptop without operating the processing hardware yourself.

Common errors and how to fix them

1. localhost:5175 does not open

The first startup may still be downloading models. Run docker compose logs to inspect progress, and wait for the initial startup to finish before trying the page again.

2. The container runs out of memory or is killed (OOM)

Treat 8 GB as a practical minimum, not spare capacity. Keeping a browser open while clipping makes memory tighter. Add RAM or run one processing job at a time.

3. GPU processing is still slow

First confirm that nvidia-smi works on the host and that NVIDIA Container Toolkit is installed. Then check that the override's GPU: "1" build argument took effect. With FFMPEG_ENCODER=auto, missing NVENC support can silently send encoding back to x264.

4. Gemini returns a quota or authentication error

The free allowance described for this setup is 1,500 requests per day, so a quota error can mean that allowance has been exhausted. For an authentication error, confirm that the key was pasted into Settings rather than an unrelated .env field. To remove the Gemini dependency, point LLM_BASE_URL and LLM_MODEL to your local service.

5. A video without speech produces no clips

The local highlight workflow needs spoken content as a basis for selection. Music-only recordings and gameplay without dialogue do not provide that transcript. Use material with speech, or use the cloud version's visual-analysis workflow for speech-free material.

FAQ

Is OpenShorts really free to self-host?

The self-hosted software is available under the MIT license without a subscription fee or expiration. Running it still uses your own hardware and electricity. Optional external services can add charges under their own billing arrangements. A locally hosted LLM replaces the Gemini dependency, provided your hardware can run a suitable model.

Do I need an NVIDIA GPU to self-host OpenShorts?

No. A modern multicore CPU and at least 8 GB of RAM can run the self-hosted workflow. An NVIDIA GPU is optional and reduces processing time when configured correctly. The GPU configuration described here targets an RTX 4060-class card with 8 GB of video memory; CPU processing remains available without it.

Does self-hosted OpenShorts add a watermark or limit how many videos I clip?

The self-hosted version does not add a watermark or impose a minute allowance. Your practical throughput depends on the machine running it, while external API quotas can constrain the steps that use those services. That differs from the cloud free plan, which includes a watermark and a 20-minute monthly allowance.

Can I post the clips straight to TikTok and YouTube?

Yes, direct publishing is available through the optional Upload-Post integration, which supports TikTok, Instagram, and YouTube. It has a free allowance, and you do not need it for local clipping and export. Enabling direct publishing involves an external provider, so that step is separate from a workflow that keeps processing entirely on your machine.