Install from source

This is the complete supported path while release images are still unpublished.

1. Check the worker

Use a Linux host or VM with:

• Docker Engine and Docker Compose v2;
• Git and OpenSSL;
• enough CPU and memory for the chosen encoder, resolution and concurrent-session limit;
• /dev/video0 for the camera path, or an X11 display for the desktop path.

docker version
docker compose version
test -S /var/run/docker.sock

macOS and Windows

You can build the TypeScript API and SDK on either system. The current camera/desktop worker contract expects Linux V4L2, X11, PulseAudio and host networking, so run full media sessions on Linux.

2. Clone the repositories side by side

mkdir tomo-streaming-local
cd tomo-streaming-local

git clone https://github.com/Tomo-Social/tomo-streaming-control-plane.git
git clone https://github.com/Tomo-Social/tomo-stream-server.git
git clone https://github.com/Tomo-Social/tomo-streaming-self-hosted.git

Expected layout:

tomo-streaming-local/
├── tomo-stream-server/
├── tomo-streaming-control-plane/
└── tomo-streaming-self-hosted/

3. Build the runtime images

From tomo-streaming-local/:

docker build \
  -t tomo-streaming-control-plane:local \
  ./tomo-streaming-control-plane

docker build \
  -f ./tomo-stream-server/Dockerfile.av \
  -t tomo-av-stream-server:local \
  ./tomo-stream-server

Confirm both tags exist:

docker image inspect tomo-streaming-control-plane:local >/dev/null
docker image inspect tomo-av-stream-server:local >/dev/null

The retro Dockerfile additionally downloads and builds Libretro cores. It is not required for the camera/desktop quickstart.

4. Configure self-hosting

cd tomo-streaming-self-hosted
cp .env.example .env
openssl rand -base64 32

Edit .env:

TOMO_STREAMING_CONTROL_PLANE_IMAGE=tomo-streaming-control-plane:local
TOMO_AV_STREAM_SERVER_IMAGE=tomo-av-stream-server:local
TOMO_STREAM_API_KEY=replace-with-the-generated-secret
STREAM_SERVER_SIGNALING_URL=ws://localhost:8090/signaling
MAX_STREAM_SESSIONS=2
TOMO_STREAM_INSTANCE_ID=local-worker

For a camera worker:

CAMERA_DEVICE_HOST=/dev/video0

For a desktop worker:

X11_SOCKET_HOST=/tmp/.X11-unix
PULSE_SOCKET_HOST=/run/user/1000/pulse

Keep unused capture variables empty.

5. Start the control plane

docker compose up -d
docker compose ps
docker compose logs -f control-plane

The control plane publishes port 8090, mounts the Docker socket and launches one host-networked stream-server container for each session.

Start with one 720p session, observe host CPU and memory, then set MAX_STREAM_SESSIONS from measured capacity rather than an assumed per-stream value.

When the service reports healthy, proceed to Verify your setup.