octoplex

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
• Terminal UI with live metrics and health
• Scriptable CLI for automation

Table of Contents

• Quick start
• 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
• Security
  • 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. Add destinations and start relaying from the TUI or CLI; see Interacting with Octoplex.

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      |
         | (Video Capture)   |   RTMP     |                   |
         +------------------+             +-------------------+
                                                 |
                                                 | 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.

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

Server flags

Client flags

All-in-one mode

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

Security

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

API tokens

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

When you run octoplex server start:

• --auth=auto (the default): if the API listen address is bound only to localhost/loopback, Octoplex requires no authentication; if it's bound to any other network interface the server generates a long random API token, logs it once on startup, hashes it to disk, and requires every client call to include --api-token "<API_TOKEN>".
• --auth=token: always require an API token, even on loopback.
• --auth=none: disable authentication completely, but only for localhost binds. If you set --auth=none with --listen-addr:0.0.0.0:50051 or any other non-localhost address you must also pass --insecure-allow-no-auth to acknowledge the risk; otherwise the server refuses to start.

The API is always served over TLS; if you don't supply a certificate Octoplex generates a self-signed one, so the token is never sent in clear-text.

ℹ Tip To regenerate a new API token, delete token.txt from the Octoplex data directory, and restart the server. See the --data-dir option in server flags.

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.

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 running Octoplex directly on the host rather than in a container.

ℹ Note: 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 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

docker-compose

---
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_ADDR: "[::]:50051" # bind to all network interfaces
    ports:
      - "50051:50051"
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:

Licence

Octoplex is released under the AGPL v3 license.