Octoplex is a Docker-native live video restreamer.

• Restream live video to unlimited destinations
• Add and remove destinations on-the-fly
• Broadcast with OBS - or any RTMP or RTSP encoder
• Automatic reconnections on drop
• Automatic TLS certificate generation for RTMPS and RTSPS
• Web and terminal UIs with live metrics and health
• Command-line interface for scripting and automation

• 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
  • Server URL
  • Incoming streams
• Restreaming with Octoplex
  • Restreaming with OBS
    • RTMP
    • RTMPS
  • Restreaming with FFmpeg
    • RTMP
    • RTMPS
    • RTSP
    • RTSPS
• Advanced
  • Running with Docker
    • docker run
    • docker-compose
• Contributing
  • Bug reports
• Acknowledgements
• Licence

1. Install Octoplex

See the Installation section below.

2. Launch all-in-one mode

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

octoplex run

3. 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. 🎉

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.

Web:

Terminal UI:

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.

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

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

Octoplex can be installed using Homebrew on macOS or Linux.

brew tap rfwatson/octoplex
brew install octoplex

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

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

See Running with Docker.

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

octoplex run

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

Docker must be running on the same machine.

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

octoplex server start

2. 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.

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

octoplex server stop

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.

octoplex client destination list --tls-skip-verify

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.

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

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

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

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

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

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

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.

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

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.

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" }

When serving Octoplex from a non-localhost domain, the server URL (set by --server-url or OCTO_SERVER_URL) must match the scheme and domain you are serving Octoplex from. Example valid values would be https://octoplex.mydomain.com or http://192.168.1.10:8080. If you observe cross-origin errors from HTTP or websocket requests, verify the server URL is set correctly.

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.

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.

Use the following OBS stream configuration:

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.

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

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

ℹ️ Tip: RTSP is disabled by default. To enable, start Octoplex with the --rtsp-enabled server flag.

ffmpeg -i input.mp4 -c copy -f rtsp -rtsp_transport tcp rtsp://localhost:8554/live

ℹ️ Tip: RTSPS is disabled by default. To enable, start Octoplex with the --rtsps-enabled server flag.

ffmpeg -i input.mp4 -c copy -f rtsp -rtsp_transport tcp rtsps://localhost:8332/live

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.

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

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.

See CONTRIBUTING.md.

Open bug reports on GitHub.

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

Octoplex is released under the AGPL v3 license.