Install an app#

You will end up with an app running on the router: on the Installed tab of the Apps page, with its own page, a menu entry for most apps, and a link to its web interface where it has one.

Before you start#

The operator role and a licence.
A route from the router to the registry the app's image comes from: Docker Hub for 30 of the catalogue's apps, GitHub's registry for the other 6.
The agent running on the router, as it does on a Wheelhouse router. An agent that runs elsewhere cannot create an app's folders; see On-router, off-router, fleet.

Step 1 — Choose the app#

Open Services → Apps. The Catalogue tab lists 37 apps and three built-in features in six categories. Search with Search apps…, or choose a category.

Read the card's badges before you install:

router network: the app uses the router's own network, and every port it opens is open on the router's addresses.
full access: the app runs with full access to the router's kernel.

Install on a built-in feature's card (WireGuard, Suricata IDS, UPnP / NAT-PMP) only adds that feature's page to the menu: nothing is downloaded and nothing is added to the pending changes. The rest of this guide is about apps.

Step 2 — Fill in the install panel#

Press Install on the app's card. In the panel that opens:

Name is filled in from the catalogue. Change it if you want another name on the router: letters, digits and hyphens.
Leave Use the router's own network off unless the app needs it. The app then gets its own Address on the app network, 10.99.0.0/24, filled in with the first free address from 10.99.0.10. An app that needs the router's network says so, and has no switch.
Fill in Settings. A required setting shows "Enter a value." until it has one, and Install stays disabled until then.
Read Before you install: the warnings for this installation, then the catalogue's notes on the app. AdGuard Home's notes, for example, say that it uses port 53 and that its setup wizard is on port 3000.
Read What this adds: the change that will go to the pending changes, such as "Add app “adguard”" with its image, address and storage.

Step 3 — Install and apply#

Press Install. Before it saves anything, Wheelhouse does the two things the router needs before it applies an app:

The button reads	What happens
Creating folders…	The folders listed under Storage are created on the router. Folders that exist are left as they are.
Downloading image…	The app's image is downloaded to the router, unless it is there already.
Saving…	The change is added to the pending changes.

The panel closes, and the notice says, for example, "AdGuard Home saved — It is installed when you apply pending changes." Press Apply changes in the bar at the bottom of the page.

The folders and the image stay on the router even if the change is removed from the pending changes instead of applied.

Step 4 — Use it#

Once the change is applied:

The app's card on the Installed tab shows its state, address, status and health check, and Open … ↗ for an app with a web interface.
Most apps get a menu entry, under Installed.
The app's page, from Manage on its catalogue card or from its card, has its settings, its log and its controls. See One app.
Offers appear on the pages the app works with. With AdGuard Home installed, the DNS page offers "Point the resolver at AdGuard Home", with Add this change. See Integration offers.

An offer's change goes to the pending changes like any other, and takes effect when it is applied.

Check it worked#

On the Installed tab, the app's badge reads running, and, for an app with a health check, its Health check line shows an answer, such as "HTTP 200".

If the badge reads not running, open the app's page. Its Log tab usually says why, and Restart now starts it again.

When it fails#

What you see	What it means
Not installed, with "pull failed" and "toomanyrequests"	Docker Hub limits downloads from each address. Try again later. Wheelhouse has no setting for registry credentials or a registry mirror.
Not installed, with another reason	The panel shows the router's reason. Most often the router cannot reach the registry.
Applying the change fails because a volume's folder does not exist	The folders were not created, which happens when the agent does not run on the router.

Undoing it#

Before the change is applied, remove it from the pending changes. After it is applied, see Stop, uninstall, and what stays behind.