octoplex

Octoplex 🐙

Octoplex is a Docker-native live video restreamer.

• Restream RTMP/RTMPS to unlimited destinations
• Broadcast using OBS or any standard tool
• Add and remove destinations on-the-fly
• Automatic reconnections on drop
• Terminal UI with live metrics and health status
• Powered by FFmpeg, Docker & other open source tools

How it works

         +------------------+             +-------------------+
         |      OBS          |  ---->     |     Octoplex      |
         | (Video Capture)   |   RTMP     |                   |
         +------------------+             +-------------------+
                                                 |
                                                 | Restream to multiple destinations
                                                 v
              +------------+     +------------+     +------------+     +--------------+
              |  Twitch.tv |     |   YouTube  |     | Facebook   |     |  Other       |
              +------------+     +------------+     +------------+     | Destinations |
                                                                       +--------------+

Installation

Docker Engine (only if you'll run Octoplex locally)

Linux: See https://docs.docker.com/engine/install/.

macOS: https://docs.docker.com/desktop/setup/install/mac-install/

Octoplex

Homebrew

Octoplex can be installed using Homebrew on macOS or Linux.

$ brew tap rfwatson/octoplex
$ brew install octoplex

From GitHub

Alternatively, grab the latest build for your platform from the releases page.

Unarchive the octoplex binary and copy it somewhere in your $PATH.

With Docker

See Running with Docker.

Starting Octoplex

Octoplex can run as a single process (all-in-one), or in a client/server pair.

All-in-one

$ octoplex run

Starts the Octoplex server and the terminal UI in one process.

Docker must be running on the same machine.

Client/server

1. Start the server (on the host that has Docker):

$ octoplex server start

1. Connect the client (from your laptop or any host):

$ octoplex client start # --host my.remotehost.com if on a different host

client start is a lightweight TUI and does not need Docker to be installed.

1. Stop the server (and clean up any Docker resources) on the remote host:

$ octoplex server stop

Subcommand reference

Server flags

Client flags

All-in-one mode

ℹ When running in all-in-one mode (octoplex run) some flags may be overridden or unavailable.

Usage

Restreaming with OBS

RTMP

Use the following OBS stream configuration:

RTMPS

Or to connect with RTMPS:

⚠ Warning: OBS may not accept self‑signed certificates.

If you see the error

"The RTMP server sent an invalid SSL certificate."

then either install a CA‑signed TLS certificate for your RTMPS host, or import your self‑signed cert into your OS’s trusted store. See the server flags section above.

Restreaming with FFmpeg

RTMP

$ ffmpeg -i input.mp4 -c copy -f flv rtmp://localhost:1935/live

RTMPS

$ ffmpeg -i input.mp4 -c copy -f flv rtmps://localhost:1936/live

Advanced

Running with Docker

octoplex server can be run from a Docker image on any Docker engine.

⚠ By design, Octoplex needs to launch and terminate Docker containers on your host. If you run Octoplex inside Docker with a bind-mounted Docker socket, it effectively has root-level access to your server. Evaluate the security trade-offs carefully. If you’re unsure, consider running Octoplex directly on the host rather than in a container.

docker run

Run the Octoplex gRPC server on all interfaces (port 50051):

docker run \
  --name octoplex                              \
  -v octoplex-data:/data                       \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e OCTO_LISTEN_ADDR=":50051"                 \
  -p 50051:50051                               \
  --restart unless-stopped                     \
  ghcr.io/rfwatson/octoplex:latest

ℹ Note: Running the client — or the all-in-one server mode — from Docker is not recommended. Install Octoplex natively via Homebrew or download a release from GitHub instead. See Installation for details.

docker-compose

See docker-compose.yaml.

Contributing

See CONTRIBUTING.md.

Bug reports

Open bug reports on GitHub.

Acknowledgements

Octoplex is built on and/or makes use of other free and open source software, most notably:

Licence

Octoplex is released under the AGPL v3 license.