octoplex

README

Octoplex 🐙

Octoplex is a Docker-native live video restreamer.

• Restream RTMP/RTMPS to unlimited destinations
• Add and remove destinations on-the-fly
• Broadcast using OBS or any RTMP encoder
• Automatic reconnections on drop
• Web user interface with live metrics and health
• Terminal UI with live metrics and health
• Command-line interface for scripting and automation

Table of Contents

• Quick start
• User interfaces
  • Screenshots
• How it works
• Installation
  • Docker Engine (only if you'll run Octoplex locally)
  • Octoplex
    • Homebrew
    • From GitHub
    • With Docker
• Starting Octoplex
  • All-in-one
  • Client/server
• Interacting with Octoplex
  • Command-line interface (CLI)
    • List destinations
    • Add a destination
    • Update a destination
    • Start a destination
    • Stop a destination
    • Remove a destination
  • Subcommand reference
  • Server flags
  • Client flags
  • All-in-one mode
• Web interface
• Security
  • TLS
  • Admin password and API tokens
  • Incoming streams
• Restreaming with Octoplex
  • Restreaming with OBS
    • RTMP
    • RTMPS
  • Restreaming with FFmpeg
    • RTMP
    • RTMPS
• Advanced
  • Running with Docker
    • docker run
    • docker-compose
• Contributing
  • Bug reports
• Acknowledgements
• Licence

Quick start

1. Install Octoplex

See the Installation section below.

1. Launch all-in-one mode

Starts the server and the terminal UI in a single process — ideal for local testing.

octoplex run

1. Point your encoder (OBS, FFmpeg, etc) at the RTMP server:

Full examples are in Restreaming with Octoplex.

rtmp://localhost:1935/live         # stream key: live

Or, if your encoder supports RTMPS:

rtmps://localhost:1936/live        # self-signed TLS certificate by default

That's it: your local restreamer is live. 🎉

User interfaces

Octoplex provides two interactive user interfaces with equivalent functionality:

• Terminal UI - Launch in your terminal for a text-based interface with real-time metrics and interactive controls.
• Web UI - Launch in your browser for a graphical user interface.

If you followed the Quick Start section, then you've already launched the terminal UI! You can try out the web interface now by visiting http://localhost:8080.

See Web interface for more.

Screenshots

Web:

Terminal UI:

How it works

Octoplex server runs on your Docker host (as a container or daemon process) and spins up MediaMTX and FFmpeg containers that ingest your feed and rebroadcast it anywhere you point them.

It handles reconnection, TLS, and container wiring so you can focus on your content.

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

⚠ Warning - alpha software: Octoplex is in active development. Features and configuration settings may change between releases. Double-check your security configuration and exercise extra caution before deploying to public-facing networks. See the Security section for more.

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.

Mode	Pick this when you...
All-in-one	Are testing locally, debugging, or streaming from the same machine that runs Docker (e.g. your laptop).
Client/server	Want the server on a remote host (e.g., cloud VM) for long-running or unattended streams.

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 interactive TUI 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

Interacting with Octoplex

Command-line interface (CLI)

Besides the interactive TUI, you can also control Octoplex with one-off command-line calls.

Don't forget to replace <PLACEHOLDER> strings with your own values.

ℹ Tip Octoplex ships with a self-signed TLS certificate by default. When connecting remotely you'll usually need --tls-skip-verify (or -k). Warning: this disables certificate validation, use only on trusted networks.

List destinations

octoplex client destination list --tls-skip-verify

Add a destination

octoplex client destination add \
    --name "<NAME>" \
    --url "<RTMP_URL>" \
    --tls-skip-verify

Make a note of the destination ID that is printed to the terminal, e.g. 036e2a81-dc85-4758-ab04-303849f35cd3.

Update a destination

octoplex client destination update \
    --id "<DESTINATION_ID>"  \
    --name "<NAME>" \
    --url "<RTMP_URL>" \
    --tls-skip-verify

Start a destination

octoplex client destination start \
    --id "<DESTINATION_ID>"  \
    --tls-skip-verify

Stop a destination

octoplex client destination stop \
    --id "<DESTINATION_ID>" \
    --tls-skip-verify

Remove a destination

octoplex client destination remove \
    --id "<DESTINATION_ID>" \
    --tls-skip-verify

ℹ Tip Pass --force (or -f) to remove the destination even if it's live.

Subcommand reference

Subcommand	Description
octoplex run	Launch both server and client in a single process
octoplex server start	Start the Octoplex server
octoplex server stop	Stop the Octoplex server
octoplex server credentials reset	Regenerate API token and admin password, and print to stdout
octoplex client start	Start the Octoplex TUI client
octoplex client destination list	List existing destinations
octoplex client destination add	Add a destination
octoplex client destination update	Update a destination
octoplex client destination remove	Remove a destination
octoplex client destination start	Start streaming to a destination
octoplex client destination stop	Stop streaming to a destination
octoplex version	Print the version
octoplex help	Print help screen

Server flags

Flag	Alias	Modes	Env var	Default	Description
--help	-h	All			Show help
--data-dir		server all-in-one credentials	OCTO_DATA_DIR	$HOME/.local/state/octoplex (Linux) or$HOME/Library/Caches/octoplex (macOS)	Directory for storing persistent state and logs
--listen	-l	server	OCTO_LISTEN	127.0.0.1:8080	Listen address for non-TLS API and web traffic. ⚠ Must be set to a valid IP address to receive connections from other hosts. Use 0:0.0.0:8080 to bind to all network interfaces. Pass none to disable entirely.
--listen-tls	-a	server	OCTO_LISTEN_TLS	127.0.0.1:8443	Listen address for TLS API and web traffic. ⚠ Must be set to a valid IP address to receive connections from other hosts. Use 0:0.0.0:8443 to bind to all network interfaces. Pass none to disable entirely.
--server-url	-u	server	OCTO_SERVER_URL	http://localhost:8080	The public address of the server, including protocol, hostname and port if necessary.
--web	-w	server	OCTO_WEB	true	Enable web server
--auth		server	OCTO_AUTH	auto	Authentication mode for clients, one of none, auto and token. See Security.
--insecure-allow-no-auth		server	OCTO_INSECURE_ALLOW_NO_AUTH	false	Allow --auth=none when bound to non-local addresses. See Security.
--tls-cert		server all-in-one	OCTO_TLS_CERT		Path to custom TLS certifcate (PEM-encoded, must be valid for hostname). Used for gRPC and RTMPS connections.
--tls-key		server all-in-one	OCTO_TLS_KEY		Path to custom TLS key (PEM-encoded, must be valid for hostname). Used for gRPC and RTMPS connections.
--docker-host		server	OCTO_DOCKER_HOST		Optional. The Docker host to connect to, e.g. ssh://user@host:2375. If not set, falls back to the Docker SDK's DOCKER_HOST environment variable or the default Unix socket.
--in-docker		server	OCTO_DOCKER	false	Configure Octoplex to run inside Docker. Set automatically to true in the Dockerfile.
--stream-key		server all-in-one	OCTO_STREAM_KEY	live	Stream key, e.g. rtmp://rtmp.example.com/live
--rtmp-enabled		server all-in-one		true	Enable RTMP server
--rtmp-listen		server all-in-one		127.0.0.1:1935	Listen address for RTMP sources. ⚠ Must be set to a valid IP address to receive connections from other hosts. See --listen.
--rtmps-enabled		server all-in-one		false	Enable RTMPS server
--rtmps-listen		server all-in-one		127.0.0.1:1936	Listen address for RTMPS sources. ⚠ Must be set to a valid IP address to receive connections from other hosts. See --listen.
--image-name-mediamtx		server all-in-one	OCTO_IMAGE_NAME_MEDIAMTX	ghcr.io/rfwatson/mediamtx-alpine:latest	OCI-compatible image for launching MediaMTX
--image-name-ffmpeg		server all-in-one	OCTO_IMAGE_NAME_FFMPEG	ghcr.io/jrottenberg/ffmpeg:7.1-scratch	OCI-compatible image for launching FFmpeg

Client flags

Flag	Alias	Default	Description
--help	-h		Show help
--host	-H	localhost:8443	Remote Octoplex server to connect to
--tls-skip-verify	-k	false	Skip TLS certificate verification (insecure)
--api-token	-t		API token. See Security.
--log-file			Path to log file

All-in-one mode

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

Web interface

Octoplex provides a built-in web interface that allows you to manage your live streams from any browser.

ℹ Note: The web interface is enabled by default. To disable it, launch Octoplex with octoplex server start --web=false.

The web interface is served from your server URL. By default this is http://localhost:8080 (or https://localhost:8443) and can be configured to a custom URL with the --server-url flag (or OCTO_SERVER_URL environment variable. See Server flags for more details.

Security

Read this section before putting Octoplex on any network you don't fully control.

Authentication

Octoplex automatically protects its internal API and web interface whenever it binds to anything other than localhost.

ℹ Tip: Octoplex never requires authentication in all-in-mode mode (octoplex run) which is designed for quick, secure local testing.

When you run octoplex server start:

• --auth=auto (the default): if the API is bound only to localhost/loopback addresses, Octoplex requires no authentication; if it's bound to any other network interface then both the web interface and API require authentication. See Admin password and API tokens.
• --auth=token: always require authentication, even on loopback.
• --auth=none: disable authentication completely, but only for localhost binds. If you set --auth=none with any non-loopback API listen addresses you must also pass --insecure-allow-no-auth to acknowledge the risk; otherwise the server refuses to start.

Admin password and API tokens

The first time Octoplex server starts with authentication enabled it generates and securely stores:

• an admin password - for accessing the web interface
• an API token - for the terminal UI and CLI

They are both printed to the logs exactly once, on first startup. After this, you won't be able to retrieve them again, but you can regenerate them:

octoplex server credentials reset     # add --data-dir "<YOUR_DATA_DIR>" if needed
# { "api_token": "foo", "admin_password": "bar" }

Incoming streams

Octoplex also listens for source streams (RTMP/RTMPS on ports 1935/1936 by default). These are not covered by the API token. To stop anyone from pushing an unsolicited feed, start the server with a unique stream key:

octoplex server start --stream-key "<YOUR_UNIQUE_STREAM_KEY>" ...
# or, set OCTO_STREAM_KEY=...

See server flags for more.

TLS

By default, the Octoplex server listens for HTTP and API traffic on ports 8080 (plain text) and 8443 (TLS with a self-signed certificate). Both listeners are bound to 127.0.0.1 unless explicitly configured otherwise. See Server flags for full configuration options.

When deploying on untrusted networks, ensure that plain-text ports are only accessible behind a TLS-enabled reverse proxy. To disable non-TLS listeners entirely, use --listen=none with octoplex server start, or set the OCTO_LISTEN=none environment variable.

Restreaming with Octoplex

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 connecting through a proxy or just running Octoplex as a daemon (non-container) process on the Docker host.

🐬 Tip: The Docker host to connect to can be configured with the --docker-host flag or OCTO_DOCKER_HOST environment variable. See Server flags.

ℹ Tip: Running the TUI client from Docker is not recommended. Install Octoplex natively via Homebrew or download a release from GitHub instead. See Installation for details.

docker run

Run the Octoplex server on all interfaces (ports 8080 and 8443/TLS):

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

docker-compose

Run the Octoplex server on all interfaces (ports 8080 and 8443/TLS):

---
services:
  octoplex:
    image: ghcr.io/rfwatson/octoplex:latest
    container_name: octoplex
    restart: unless-stopped
    volumes:
      - octoplex-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      OCTO_LISTEN: "[::]:8080"     # bind to all network interfaces
      OCTO_LISTEN_TLS: "[::]:8443" # bind to all network interfaces
    ports:
      - "8080:8080"
      - "8443:8443"
volumes:
  octoplex-data:
    driver: local

See also 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:

Name	License	URL
Docker	Apache 2.0	GitHub
FFmpeg	LGPL	Website
MediaMTX	MIT	GitHub
tview	MIT	GitHub

Licence

Octoplex is released under the AGPL v3 license.