heroeswearkapes/ffmpeg-ssh-worker repository overview

⁠FFmpeg SSH Worker

A lightweight, CPU-based FFmpeg rendering worker with secure SSH key authentication for automation workflows.

FFmpeg SSH Worker was originally created as the rendering node for an n8n workflow that automatically assembled YouTube Shorts. n8n connected to the worker over SSH, executed FFmpeg commands, and used a shared workspace for source media, intermediate files, and completed renders.

Although originally built for n8n, the worker is not tied to it. Any automation platform, script, or application capable of executing commands over SSH can use the container as an isolated FFmpeg processing node.

No GPU is required. Media processing and encoding are performed using the host CPU.

⁠Features

• FFmpeg 8
• CPU-based media processing and encoding
• OpenSSH server
• SSH public-key authentication
• Password authentication disabled
• Root SSH login disabled
• Persistent SSH host keys
• Persistent /config directory
• Shared /work rendering workspace
• H.264 encoding with libx264
• H.265/HEVC encoding with libx265
• Fontconfig and DejaVu fonts
• Python 3, curl, jq, gawk, and other automation utilities
• Docker healthcheck
• Docker Compose support
• Unraid Community Applications support
• Multi-architecture images
  • linux/amd64
  • linux/arm64

⁠Pull

docker pull heroeswearkapes/ffmpeg-ssh-worker:latest

Versioned releases are also available:

docker pull heroeswearkapes/ffmpeg-ssh-worker:v1.0

⁠Quick Start

Create directories for persistent configuration and media processing:

mkdir -p config work

Add your SSH public key:

cp ~/.ssh/id_ed25519.pub config/authorized_keys

Start the worker:

docker run -d \
  --name ffmpeg-ssh-worker \
  -p 2222:22 \
  -e TZ="America/New_York" \
  -v "$(pwd)/config:/config" \
  -v "$(pwd)/work:/work" \
  --restart unless-stopped \
  heroeswearkapes/ffmpeg-ssh-worker:latest

Connect:

ssh -p 2222 worker@YOUR-SERVER-IP

The default SSH username is:

worker

Password authentication is disabled. An SSH public key is required.

⁠Docker Compose

The project includes a Docker Compose configuration.

services:
  ffmpeg-ssh-worker:
    image: heroeswearkapes/ffmpeg-ssh-worker:latest
    container_name: ffmpeg-ssh-worker

    environment:
      TZ: ${TZ:-America/New_York}

    ports:
      - "${SSH_PORT:-2222}:22"

    volumes:
      - ${CONFIG_PATH:-./config}:/config
      - ${WORK_PATH:-./work}:/work

    restart: unless-stopped

Create your configuration:

cp .env.example .env
mkdir -p config work
cp ~/.ssh/id_ed25519.pub config/authorized_keys
docker compose up -d

⁠SSH Authentication

FFmpeg SSH Worker uses public-key authentication.

The preferred public-key location is:

/config/authorized_keys

Only place your public key in this file.

Never copy your SSH private key into /config.

Multiple public keys are supported using the standard OpenSSH authorized_keys format, with one public key per line.

⁠Persistent Configuration

The /config directory stores:

/config/authorized_keys
/config/ssh_host_ed25519_key
/config/ssh_host_ed25519_key.pub
/config/ssh_host_rsa_key
/config/ssh_host_rsa_key.pub

SSH host keys are generated automatically.

Keeping /config persistent preserves the SSH server identity when the container is recreated or upgraded.

⁠Work Directory

The primary FFmpeg workspace is:

/work

Use it for:

• Source videos
• Images
• Audio
• Intermediate media
• Rendered videos
• Completed output

For example:

ffmpeg \
  -i /work/input.mp4 \
  -c:v libx264 \
  -preset medium \
  -crf 23 \
  -c:a aac \
  /work/output.mp4

The worker account must have permission to write to the host directory mapped to /work.

⁠CPU Rendering

FFmpeg SSH Worker intentionally uses CPU-based rendering.

No NVIDIA, Intel, or AMD GPU passthrough is required.

H.264 example:

ffmpeg \
  -i /work/input.mp4 \
  -c:v libx264 \
  -preset medium \
  -crf 23 \
  -c:a aac \
  /work/output.mp4

H.265/HEVC example:

ffmpeg \
  -i /work/input.mp4 \
  -c:v libx265 \
  -preset medium \
  -crf 28 \
  -c:a aac \
  /work/output.mp4

Performance depends on the host CPU, resolution, frame rate, filters, encoder settings, and number of simultaneous jobs.

⁠Using with n8n

FFmpeg SSH Worker was originally created for n8n.

The basic architecture is:

n8n
 |
 | SSH
 v
FFmpeg SSH Worker
 |
 |-- source media
 |-- FFmpeg processing
 |-- intermediate files
 `-- completed render

A typical n8n SSH credential uses:

Host: YOUR-WORKER-IP
Port: 2222
Username: worker
Authentication: Private Key

The corresponding public key is placed in:

/config/authorized_keys

on the worker.

The private key remains with n8n.

An n8n SSH node can then execute FFmpeg commands such as:

ffmpeg -y \
  -i /work/source.mp4 \
  -i /work/music.mp3 \
  -c:v libx264 \
  -preset medium \
  -c:a aac \
  -shortest \
  /work/final-video.mp4

This keeps workflow orchestration separate from CPU-intensive media rendering.

⁠Other Uses

The worker can also be used for:

• Automated video rendering
• YouTube Shorts generation
• Social-media video assembly
• Video transcoding
• Audio conversion
• Audio/video muxing
• Image-to-video workflows
• Subtitle processing
• Text overlays
• Thumbnail and frame extraction
• Batch media processing
• Custom automation workflows

⁠Unraid

FFmpeg SSH Worker supports Unraid Community Applications.

The Unraid template provides configuration for:

• SSH port
• Persistent /config
• FFmpeg /work directory
• Timezone

The default SSH user is:

worker

After installation, place your SSH public key at:

/mnt/user/appdata/ffmpeg-ssh-worker/authorized_keys

Then restart the container.

With the default port configuration:

ssh -p 2222 worker@YOUR-UNRAID-IP

No GPU configuration is required.

⁠Healthcheck

The container includes a healthcheck that verifies the SSH server is listening on port 22.

Check status with:

docker ps

A healthy status confirms that the SSH service is listening. It does not validate SSH credentials or execute an FFmpeg render.

⁠Security

The SSH server is configured with:

• Root login disabled
• Password authentication disabled
• Public-key authentication enabled
• SSH access restricted to the worker account

Recommended practices:

• Use strong SSH keys such as ED25519.
• Never place private SSH keys in /config.
• Only add trusted public keys to authorized_keys.
• Avoid exposing the SSH port directly to the public Internet.
• Prefer trusted LANs, VLANs, VPNs, or private overlay networks.
• Remove SSH keys that are no longer needed.
• Keep the container image updated.

⁠Multi-Architecture

Published images support:

linux/amd64
linux/arm64

The same image can therefore run on standard x86-64 Docker hosts and compatible ARM64 systems.

⁠Documentation & Source

Full installation instructions, Docker Compose configuration, n8n examples, troubleshooting, source code, and Unraid documentation:

https://github.com/heroeswearkapes/ffmpeg-ssh-worker⁠

⁠Project History

FFmpeg SSH Worker began as a dedicated CPU rendering node for an automated YouTube Shorts workflow built with n8n.

The original worker has since been redesigned and documented as a general-purpose SSH-accessible FFmpeg processing container while retaining its original n8n use case.

⁠License

MIT License.

See the project repository for the complete license text.

⁠Disclaimer

This is an independent community project.

It is not affiliated with or endorsed by FFmpeg, n8n, Docker, Ubuntu, Unraid, or any other third-party project referenced in this documentation.