Install Middlewarr

Middlewarr runs as one container with a web dashboard and a Go server. It listens on port 80 inside the container and stores its persistent state in /data.

This guide builds from the application source. It does not depend on a prebuilt container image.

Before you start

You need Docker with Compose, Git, and an existing Radarr, Sonarr, Lidarr, or Prowlarr instance. The Middlewarr container must be able to reach that instance.

Allow network access to download the build dependencies, template repositories, and the upstream OpenAPI specifications. Keep the same data directory between container recreations.

1. Get the source

Source access

This guide requires an application source checkout. As of 6 September 2026, the planned public repository below is not available to unauthenticated visitors. Use a checkout you already have access to, or use the clone command once that repository is available to you.

The planned application repository is in the Middlewarr organization:

git clone https://github.com/middlewarr/middlewarr.git
cd middlewarr

If you already have an application checkout, use its root directory. The Compose configuration below expects the application’s Dockerfile, server/, and web/ directories beside it.

2. Create the data directory

mkdir -p data
cp settings.sample.yml data/settings.yml

The configuration file must exist before startup. The supplied sample binds the server to 0.0.0.0 so the published container port is reachable.

3. Add a Compose file

Create compose.yaml in the application checkout:

services:
  middlewarr:
    build: .
    image: middlewarr:local
    ports:
      - "9292:80"
    volumes:
      - ./data:/data
    environment:
      LOG_LEVEL: "1"
    restart: unless-stopped

9292 is the port you will open in your browser; 80 is the container port. The image name labels the image you build locally.

This port mapping accepts connections on the host’s interfaces. Use it on a trusted network. If a reverse proxy on the same host will be the only entry point, bind it to loopback instead with 127.0.0.1:9292:80. See Security and HTTPS.

4. Build and start

docker compose up -d --build
docker compose logs --tail=100 middlewarr

Open http://YOUR_HOST:9292 in your browser, replacing YOUR_HOST with the server’s address. On the server itself, try http://localhost:9292.

For a basic server check:

curl --fail http://localhost:9292/health

A successful health response confirms Middlewarr is responding. It does not prove an upstream service or a proxy is configured correctly.

5. Create the administrator

The first-run screen asks for a username, password, and bootstrap token. Use a password of 12–128 characters.

Find the line containing “one-time token” in the startup logs and paste its value into Bootstrap token. The browser sends the required header for you. The token is required for a remote connection; a connection the server recognizes as loopback can set up without it. Container networking and reverse proxies can make a local browser connection appear remote, so use the token if setup asks for it.

Store your administrator credentials in your password manager. This is one local administrator account; there is no email-based password reset. Lost-password recovery requires access to the host.

Next: make a request

A running container has no configured services or proxies. Continue with Your first proxy to connect an upstream service and verify both allowed and blocked requests.

If the container exits or the page will not open, start with Troubleshooting.