Network Modes

Network mode is set once at norsk-ctl init and determines how containers communicate with each other and the outside world. Two modes — docker and hybrid — trade off isolation against media-ingest latency. An instance’s UI always sits behind the reverse proxy in both modes; they differ only in where the instance’s media container runs.

Quick decision matrix

Use case	Mode	Why
Multi-instance, production server	docker (default)	Full isolation, single TLS entry point, no host-port collisions on instances’ internal ports
Lowest latency media ingest	hybrid	UI services on the bridge behind the proxy; media on the host for kernel-direct UDP

Caution

macOS / Docker Desktop only supports docker mode. hybrid relies on Linux host networking, which Docker Desktop’s VM doesn’t surface. The interactive init wizard greys it out on macOS.

Two planes: UI and media

Split every deployment into two planes, and network mode only touches the second. The split is the same for every product template; the examples below use a single Norsk Studio instance named live.

The UI + API plane is always proxied. A browser (or MCP host) only ever talks to nginx on :443. nginx terminates TLS, authenticates, then routes /instance/<id>/… to the instance’s UI services and /api/, /mcp, / to the daemon. An instance never binds a public UI port of its own. This is identical in docker and hybrid.

The media plane is what the mode decides. Norsk Media’s stream ingest and egress (SRT, RTMP, WebRTC, …) reach the host either through the Docker bridge (docker) or straight off the host network (hybrid), and Studio’s control link to Media follows the same path. The two sections below show that plane for the live instance.

Docker mode

Both containers — Studio and Media — sit on the norsk-net Docker bridge. Media’s stream ports are published from the container to the host through Docker’s port mapping (a NAT hop), and Studio reaches Media by container name across the bridge. nginx fronts everything: the Studio UI and Media’s monitoring endpoints (/instance/<id>/media/, visualiser, metrics).

This is the default and recommended mode for production. Multiple concurrent instances coexist without port conflicts — each instance’s containers are resolved by name on the bridge, not by a shared host port. Auth and TLS are enforced at the proxy.

Initialise with:

norsk-ctl init --network-mode docker --proxy-user admin --proxy-password <pass>

Access the instance’s runtime UI at https://<public-host>/instance/<id>/ (Studio’s canvas lives at /instance/<id>/studio/).

Hybrid mode

Studio still sits on the bridge behind the proxy — UI access is identical to docker. Norsk Media instead joins the host network: its stream ports bind kernel-direct on the host with no Docker NAT hop, and Studio reaches it via host.docker.internal. This is the lowest-latency path for media ingest — stream traffic never traverses the Docker network stack.

Initialise with:

norsk-ctl init --network-mode hybrid --proxy-user admin --proxy-password <pass>

Access the instance the same way as docker mode: https://<public-host>/instance/<id>/.

Note

Even in hybrid, Norsk Media’s monitoring endpoints (visualiser, metrics, status) stay proxied under /instance/<id>/… — nginx just reaches them via the host instead of the bridge. It’s the media stream plane that goes direct.

Default proxy port

Both modes default the proxy to HTTPS on port 443. The legacy 9080 / 9443 docker defaults are gone — norsk-ctl init mandates a cert source, so HTTPS is always on. Override with --proxy-port N at install / init time, or proxyPort: in config.yaml. See Ports.

Switching modes

Changing network mode requires re-initialising:

norsk-ctl init --network-mode <new-mode> --force

Stop all running instances first. The --force flag overwrites the existing config.yaml.