Using Inspector

1. First login

When Inspector starts for the first time it creates its config file and a dashboard login.

1. If you set INSPECTOR_PASSWORD in the Portainer stack, sign in with admin (or your INSPECTOR_USERNAME) and that password.
2. If you didn't, Inspector generated a password. In Portainer open Containers → inspector → Logs. Near the top you'll see a box labeled Inspector dashboard login with the username and password.
3. Open http://<your-server>:8080 and sign in.
4. Change the password under Settings → Dashboard if you like.

2. Add your containers

Inspector only watches containers you add. Go to Settings and click + Add container at the bottom of the left menu (or + New container on the All containers page).

1. name: the container's name exactly as Portainer shows it (for example sonarr). If it doesn't match, the card shows CONTAINER NOT FOUND.
2. Leave enabled on.
3. Under Restart when status is… click Recommended (restarts on UNHEALTHY and NOT RUNNING), or Observe only if you just want alerts without restarts.
4. Click Create container. Inspector starts watching it on its next check (within a minute by default). No restart needed.

What the numbers mean

3. The Status page

The top row counts containers, healthy ones, ones with issues, and ones in maintenance. Each card shows:

• Status badge: what Docker reports right now, e.g. HEALTHY NOT RUNNING NO HEALTH CHECK (the image has no health check; that's normal for many apps and only means Inspector can tell running from stopped, not healthy from unhealthy).
• Errors bar: bad checks in a row out of max_error_count. When it fills, Inspector restarts the container.
• Cooldown until / Last restart: when Inspector last restarted it and when it's allowed to again.
• Observe only: shown when the container has no restart triggers; Inspector alerts but never restarts it.
• Enter maintenance: pause Inspector for that container while you work on it (updates, migrations). Click again to exit.
• Mute notifications: keep watching and restarting, but stop alerts for a while (12 hours by default).

The page refreshes itself every 30 seconds.

4. Notifications

Inspector can alert you through Gotify, Pushover, or both. Set them up under Settings → Notifications.

1. Turn on enabled for the channel you use.
2. Gotify: enter your server URL and an application token (create one in Gotify under Apps). Pushover: enter your application API token and your user key.
3. Click Send test. You should get a message on your phone within seconds. If it fails, the reason appears next to the button.
4. Click Save, then restart Inspector once (see section 10), because turning a channel on or off is a "requires restart" field.

You'll get one alert when a container first fails, when Inspector restarts it, and when it recovers. You won't get one on every check.

5. Managing containers

Settings → All containers shows every watched container as a tile. Click a tile (or a name in the left menu) to edit it.

Changes apply on the next check. Delete container stops Inspector watching it; it does not touch the container itself.

Restart triggers

Reachability: catching apps that look fine but aren't

Docker only knows whether a container is running and whether its own health check passes. An app can pass both and still be unusable, for example when it routes through a VPN container whose tunnel dropped. Under Reachability on the container page you can add:

• HTTP check: a URL Inspector requests every check (for example http://192.168.1.10:9696/ping). Set expected_status to the code the app returns when it's healthy; most return 200, some return 401 or 302.
• Uptime Kuma monitor: if you already run Uptime Kuma, name one of its monitors. Set up the connection first in Settings → Uptime Kuma; Test connection lists the monitor names it can see.

A failed check reports UNREACHABLE. Tick UNREACHABLE in the restart triggers if you want Inspector to act on it.

6. Apps behind a VPN container

Why these apps need special handling

A common setup routes download and indexer apps through a VPN container. Those apps don't get a network of their own: their compose file says network_mode: container:<vpn> (or service:<vpn>) and all their traffic goes through the VPN container. That causes two problems for a watchdog:

• When the VPN breaks, every app behind it breaks at the same time. Restarting the apps does nothing while the tunnel is down. Without help, Inspector would restart each app over and over, use up their hourly restart limits, and flood you with alerts, all for a problem in a different container.
• When the VPN container is recreated (an image update, or someone redeploys its stack), it gets a new container ID. The apps still point at the old one, so a normal restart fails with errors like "No such container" or "joining network namespace". The only fix is to recreate the apps too, which is what a Portainer stack redeploy does (section 7).

How to tell if an app is behind a VPN

• In Portainer open Stacks → your stack → Editor and look for network_mode: container:… or network_mode: service:… on the app.
• Or open Containers → the app: under Network it shows the VPN container instead of a normal network, and it has no ports of its own (they're published on the VPN container).

Setting it up

1. Add the VPN container to Inspector and keep it enabled (restart on UNHEALTHY and NOT RUNNING is a good start). Inspector can only wait for containers it is watching: if the VPN container is disabled, its apps are recovered normally, as if there were no dependency, and the container page shows a warning.
2. On each app behind it, set Dependencies → depends_on to the VPN container.
3. Turn on vpn_routed. This only changes the log: Inspector writes down when it holds off on the app because the VPN is down. The waiting itself comes from depends_on.
4. Add an HTTP check (section 5) using your server's IP and the port published on the VPN container, and tick UNREACHABLE. Docker often still reports these apps as healthy when the tunnel is down; the HTTP check notices.
5. Under Recovery, choose Restart, then redeploy stack if that fails and enter the stack name. This needs the Portainer connection from section 7.

What Inspector then does

Every check, it looks at the VPN container first. While the VPN is anything other than healthy (or starting, or running without a health check), the apps that depend on it are not restarted; Inspector fixes the VPN first. Once the VPN is healthy again, the apps are handled normally: a restart first, and a stack redeploy if the restart fails or doesn't help.

depends_on isn't only for VPNs. Use it for any "B needs A" pair, such as an app and its database: Inspector won't restart the app while its database is down.

7. Portainer stack redeploy

Why Inspector needs Portainer

Inspector talks to Docker directly, so it can restart or start a container. It can't recreate one: that needs the container's compose definition, which lives in Portainer. A stack redeploy asks Portainer to do exactly what its Update the stack button does. That's how VPN-routed apps get reattached to a recreated VPN container. You only need this if you use one of the two "redeploy" recovery actions.

A redeploy affects the whole stack. Portainer pulls the latest images and recreates every container in that stack, not just the failing app, so all of them blink off for a moment. That's why Restart, then redeploy stack if that fails is the recommended choice: most problems are fixed by the plain restart, and the redeploy is only used when that doesn't work.

Requirements

• The app must belong to a stack that was created in Portainer. In Stacks, stacks created elsewhere (for example with docker compose on the command line) are marked Limited, and Portainer can't redeploy them.
• An access token for a Portainer user who can manage that stack. An administrator's token is the simplest.

Step 1: find the values

Step 2: give Inspector the token

Recommended: an environment variable. The token then never lands in config.yml or its backups.

1. In Portainer open Stacks → inspector → Editor.
2. Check that the compose file has this line under environment: (it's in the compose file from version 0.9.1 on; add it if your stack is older): - PORTAINER_API_TOKEN=${PORTAINER_API_TOKEN:-}
3. Under Environment variables click Add an environment variable: name PORTAINER_API_TOKEN, value the token.
4. Click Update the stack. Inspector restarts with the token available.

Alternative: save it in Inspector. In the next step choose Saved in config.yml and paste the token. It is masked in the dashboard, but anyone who can read Inspector's config folder (or a backup of it) can read the token.

Step 3: connect Inspector

1. Open Settings → Portainer. Under Add environment, give it a name (your own label, e.g. home) and fill in base_url, endpoint_id and verify_ssl.
2. API token stored as: Environment variable with the name PORTAINER_API_TOKEN, or Saved in config.yml with the token.
3. Click Test connection. It should list the stacks on that endpoint; check that your app's stack is there. Then Save new environment.
4. At the top of the page turn enabled on, pick the default_environment, and Save Portainer.
5. On each app's container page, set the recovery action and stack name (section 6). Leave portainer_environment on Default unless you connected more than one Portainer.

The other settings on the page

If Test connection fails

8. Events history

The Events tab is a day-by-day timeline of failures, restarts, recoveries, mutes, and maintenance. Use Prev day / Next day to look back.

9. Other settings

At the bottom of every settings page is a strip showing where the config file lives and whether Inspector can write to it.

10. "Requires restart" fields

Most changes apply on the next check. Fields marked REQUIRES RESTART (like turning a notification channel or the dashboard on or off) only take effect after Inspector restarts:

1. In Portainer go to Containers.
2. Tick inspector and click Restart.

Your settings and history are kept; they live in the folders mounted into the container.

11. Troubleshooting