Labels and Modes

Decide which containers Outpost updates, which it only watches, and which it leaves alone, using two container labels and two settings.

Why Use This Feature?

Lets you update everything by default and carve out the few services that need care so a big host stays low-maintenance.
Lets you start with nothing and opt services in one at a time so you build trust before Outpost touches anything important.
Keeps databases and other sensitive services monitor-only so you hear about new images but choose when to apply them.

Labels

Label	Value	Effect
`io.cbnventures.outpost.enable`	`true` or `false`	Opts a container in or out, depending on the label mode.
`io.cbnventures.outpost.monitor-only`	`true`	Reports a newer image for this container without recreating it.

Values are matched exactly, so True, yes, or 1 have no effect.

Label Mode

Choose Container selection on the Settings page to set the starting point.

Opt-Out (Default)

Every running container is checked unless it has io.cbnventures.outpost.enable=false:

compose.yml

yaml

services:
  postgres:
    image: postgres:17
    labels:
      # Never touch the database.
      io.cbnventures.outpost.enable: "false"

Opt-In

Only containers with io.cbnventures.outpost.enable=true are checked:

compose.yml

yaml

services:
  web:
    image: ghcr.io/example/web:latest
    labels:
      io.cbnventures.outpost.enable: "true"

Containers that are left out by the label rules don't appear in the report at all.

Monitor-Only

A monitor-only container is checked like any other, but when a newer image exists it is reported as available instead of being recreated. You can turn it on in two ways:

For one container — Add io.cbnventures.outpost.monitor-only: "true" to it.
For everything — Turn on Monitor only on Outpost's Settings page.

compose.yml

yaml

services:
  home-assistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    labels:
      io.cbnventures.outpost.monitor-only: "true"

Every check that finds a newer image for a monitor-only container sends the New images available alert to the destinations that chose it, as described in Notifications.

info

When the registry can't report a digest, Outpost falls back to pulling the image to compare it. In that case a monitor-only container's new image is downloaded, but the container is still left as it is.

Outpost Itself

Outpost follows the same labels for its own container, so it keeps itself current without a manual pull:

Opt-out mode — Outpost updates itself unless its container has io.cbnventures.outpost.enable=false.
Opt-in mode — Outpost updates itself only when its container has io.cbnventures.outpost.enable=true, like every other container.
Monitor-only — Outpost reports a newer image of itself as available instead when its container has io.cbnventures.outpost.monitor-only=true or Monitor only is on in Settings.

To keep Outpost on the image it runs now, label it off:

compose.yml

yaml

services:
  outpost:
    image: cbnventures/outpost:latest
    labels:
      # Keep Outpost on its current image.
      io.cbnventures.outpost.enable: "false"

Outpost checks itself last in every cycle, and you can also check it on its own from the dashboard or the API. How Outpost Updates Itself explains the swap and what it needs.

Outpost finds its own container from Linux process metadata, with Docker's container-ID hostname as a fallback. If it can't, it leaves alone every container running an image named outpost, such as cbnventures/outpost:latest, so it never stops itself in the middle of a check.

Containers Outpost Always Skips

Some containers are never recreated, even when the label rules select them. Those that are selected appear in the report as skipped with a reason:

Container	Reason shown
Outpost container, when Outpost can't find its own	`Outpost couldn't find its own container, so it leaves Outpost containers alone`
Image pinned to a digest, such as `nginx@sha256:...`	`Image is pinned to a digest or ID`
Locally built image the registry doesn't have	`Image is locally built or has no published registry digest`
Locally built image, or a private one without credentials	`Image is locally built, or its registry needs credentials Outpost doesn't have`
`network_mode: container:...` or `service:...`	`Shares another container's network namespace`
Container whose network namespace another uses	`Has containers sharing its network namespace`
Container started with `--rm`	`Container is configured for automatic removal`

Outpost decides that an image is locally built like this:

Docker 29, or the classic image store — Docker records where each image came from. An image built on this host gets the first message without any registry being asked, even when a registry publishes the same name, and a pulled image is checked like any other.
Docker 28 or older with the containerd image store — Docker keeps no such record, so Outpost asks the registry and skips the image only when the registry doesn't have it or won't show it without a login. Docker Hub answers a missing name as if it needed a login, so local builds there get the second message, and so does a pulled private image when Outpost has no sign-in for its registry.
Registry can't be reached — Outpost tries the pull instead, and a failed pull shows as failed.

A container the label rules leave out never reaches these checks, so it gets no skipped line, and that includes Outpost itself. Stopped containers are not checked either, because Outpost only looks at running containers.

Dependency Order

Within a Compose project, services listed under depends_on are checked and updated before the services that depend on them. A database is updated before the app that uses it, for example.

Containers from different projects, or started without Compose, keep the order Docker lists them in.