Apps#

Services → Apps installs apps on the router and manages them. An app is a program that runs in a container on the router, such as a DNS filter, a VPN client or a monitoring tool. It is part of the router's configuration: installing an app, changing its settings, stopping it and uninstalling it are pending changes, applied with Apply changes in the bar at the bottom of the page, and each applied change is a revision on System → History.

The page has four tabs:

Tab	Shows
Catalogue	The apps and built-in features that can be installed. This page.
Installed	The installed apps and built-in features. See Apps — installed.
Containers	Every container on the router, compared with the configuration. See the Containers tab.
Images	The container images on the router. See Apps — images.

The tiles#

Tile	Shows
Available	The number of entries in the catalogue, with the number of categories beneath.
Installed	The number of installed apps.
Running	How many installed apps are running. Amber when fewer are running than are installed.
Unhealthy	How many running apps fail their health check, red when any do. Beneath it: "Health check failing" or "All health checks pass".

The catalogue#

The catalogue has 40 entries: 37 apps that run in containers, and three features built into the router — WireGuard, Suricata IDS and UPnP / NAT-PMP. They are grouped in six categories (DNS & filtering, VPN & remote access, Monitoring, Security, Network services, Management) and sorted by name within each.

The Search apps… box, on this tab only, matches an entry's name, its one-line description, its full description and its tags. The chips below the tiles show All entries or one category, each with its number of entries. When nothing matches, the tab reads "No apps match" followed by the search.

An app's card#

A card shows the app's name and category, a one-line description, badges, and the image the app runs.

Badge	Means
router network	The app uses the router's own network. It has no address of its own, 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.
web interface	The app has a web interface. Once the app is installed, its card and its page link to it.
(others)	Up to two of the app's tags.

The image is shown in full, with its digest. Every container image in the catalogue is pinned by digest (name:tag@sha256:…), so an app installed from the catalogue runs exactly the image the catalogue names.

Install opens the install panel described below. It needs the operator role; a viewer sees it disabled, with "Installing apps needs the operator role". Once the app is installed, the card shows the app's state badge and Manage, which opens the app's page. Documentation ↗ opens the app's own documentation.

A built-in feature's card#

A built-in feature is already part of the router; installing it adds its page to the menu. Its card has a built in badge and the line "Built into the router. Installing adds its page to the menu."

Install adds the page to the menu. Nothing is downloaded and nothing is added to the pending changes.
Once installed, the card shows Open, which goes to the page, and Uninstall, which takes the page out of the menu.
If the feature still has settings on the router, its page stays, and Uninstall adds the removal of all of those settings to the pending changes. The notice says: "Its settings are still configured, so its page stays until they are removed. Their removal has been added to the pending changes." To keep the settings, remove that change from the pending changes before applying.
A feature with settings on the router has its page in the menu whether or not it was installed here. The UPnP page also stays in the menu while UPnP is turned on.

Installing and uninstalling a built-in feature is recorded in the audit log.

Catalogue source#

Below the cards, the Catalogue source panel says where the catalogue came from.

Item	Shows
Badge	built in: the catalogue built into this version of Wheelhouse. signed #N: a signed catalogue update, verified against a key built into Wheelhouse. update refused is added when a published update was refused, and update ready when a newer catalogue has been verified and will be used the next time the agent starts.
The sentence	Where the catalogue came from, and why an update is not in use.
Signing key, Issued	For a signed catalogue: the key that verified it, and when it was issued.
Updates	Downloaded and verified when the router checks for updates (the Updates panel on the System page), Not downloaded when it does not.
Update address, Last checked, Last check failed	Where updates come from, and the result of the last check.

Advanced mode adds Verified copy, the file the verified catalogue is kept in.

This version of Wheelhouse has no catalogue signing key built in, so it uses the built-in catalogue, and the sentence reads: "This is the catalogue built into this version of Wheelhouse. No catalogue signing key is compiled in, so updates to it are not downloaded."

Installing an app#

Press Install on the app's card. A panel opens, titled Install and the app's name, starting with the app's description.
Under Where it runs, check the app's Name on the router. It is filled in from the catalogue and takes letters, digits and hyphens.
Choose the network. With Use the router's own network off, the app gets its own Address on the app network, 10.99.0.0/24; the field is filled in with the first free address from 10.99.0.10. With it on, the app shares the router's interfaces and has no address of its own. An app that needs the router's network shows "This app uses the router's own network." in place of the switch.
Fill in Settings: one field for each setting the app declares, labelled with the setting's name and described beneath. Values the catalogue provides are filled in. A required setting left empty shows "Enter a value.", and Install stays disabled until it has one. A secret setting hides what is typed.
Read the rest of the panel:
- Ports: the ports the app listens on, with the protocol and what each is for.
- Storage: each folder the app keeps its files in, on the router and inside the app. They are kept on the router across upgrades.
- Before you install: warnings about this installation, then the catalogue's notes on the app.
- Integrations: the offers the app makes on other pages once it is installed, and the page each appears on. See Integration offers.
- What this adds: the change as it will read in the pending changes. Advanced mode shows the commands instead, under Commands.
Press Install. The button shows each step as it runs: Creating folders… for an app with storage, Downloading image… when the image is not on the router yet, then Saving…. The panel closes, and the notice says "AdGuard Home saved — It is installed when you apply pending changes."
Press Apply changes in the bar at the bottom of the page.

The router does not apply an app whose image or folders are missing, so Wheelhouse creates the folders and downloads the image before it saves the change. Neither is configuration: removing the change from the pending changes leaves the folders and the image on the router. The image can be removed on the Images tab.

If a step fails, the change is not saved, and the panel shows Not installed with the reason.

The warnings under Before you install are:

"Uses the router's own network: every port it opens is open on the router's addresses."
"Enter a value for TS_AUTHKEY.", naming a required setting that is empty.
"Runs with full access to the router's kernel."

What an install adds#

The pending changes gain one change for the app, such as "Add app “adguard”", with its image, its address or the router's network, its settings and its storage listed beneath. The permissions the catalogue grants the app, and a memory limit where the catalogue sets one, are part of the same change. Settings left empty are not added.

When the router has no app network yet, the install also adds it: "Add app network “apps”", prefix 10.99.0.0/24. An app on the router's own network does not need it.

For automation#

An install is these calls, in this order. Each needs the operator role, and all but the first need a licence.

Call	Does
`POST /api/apps/plan`	Answers the operations an install would add, its warnings, and whether the image is on the router. Adds nothing.
`POST /api/apps/prepare`	Creates the app's folders, from `{"app_id": "adguard"}`. Folders that exist are left alone.
`POST /api/apps/pull`	Downloads the app's image, from `{"app_id": "adguard"}`.
`POST /api/stage`	Adds the plan's operations to the pending changes.

GET /api/apps/catalog answers the catalogue with its source, and POST /api/apps/feature with {"id": "wireguard", "enable": true} installs a built-in feature. The endpoint index lists them all.