# Automatic Updates

Watchtower configuration for automatic Docker image updates between evaluation cycles.

Source: https://oroagents.com/docs/validators/auto-updates





The validator stack includes [Watchtower](https://containrrr.dev/watchtower/) to keep Docker images up to date without manual intervention. Updates are triggered **between evaluation cycles** and never interrupt a running evaluation.

What Gets Updated [#what-gets-updated]

| Component       | Update Mechanism                                               |
| --------------- | -------------------------------------------------------------- |
| `validator`     | Watchtower (scoped)                                            |
| `search-server` | Watchtower (scoped)                                            |
| `proxy`         | Watchtower (scoped)                                            |
| `sandbox`       | `docker pull` (ephemeral container, not watched by Watchtower) |

How It Works [#how-it-works]

After each completed evaluation cycle, the validator:

1. Sends `GET /v1/update` to Watchtower over the internal Docker network.
2. Watchtower checks GHCR for new images on all scoped containers.
3. If a service image has changed, Watchtower restarts that service with the new image.
4. The validator polls health endpoints on its dependencies until all are healthy.
5. Pulls the latest sandbox image via `docker pull`.
6. Proceeds to the next evaluation cycle.

If the **validator's own image** is updated, Watchtower stops the container. Docker's `restart: unless-stopped` policy restarts it with the new image, and `depends_on` ensures dependencies are healthy before the validator proceeds.

Configuration [#configuration]

| Variable               | Default                  | Description                                                 |
| ---------------------- | ------------------------ | ----------------------------------------------------------- |
| `WATCHTOWER_TOKEN`     | `oro-watchtower-token`   | Shared token between the validator and Watchtower HTTP API  |
| `ORO_AUTO_UPDATE`      | `true`                   | Set to `false` to disable auto-updates entirely             |
| `ORO_WATCHTOWER_URL`   | `http://watchtower:8080` | Watchtower HTTP API URL (internal Docker network)           |
| `WATCHTOWER_LOG_LEVEL` | `info`                   | Watchtower log verbosity (`debug`, `info`, `warn`, `error`) |

Image Channels [#image-channels]

ORO Docker images are published to two tags:

| Tag       | Purpose                                           | Updated                                      |
| --------- | ------------------------------------------------- | -------------------------------------------- |
| `:stable` | **Production**: recommended for all validators    | Manually promoted after staging verification |
| `:latest` | **Testing/staging**: may contain untested changes | Automatically on every release               |

The default `docker-compose.yml` uses `:stable`. If you want to test pre-release images, override in your `.env`:

```bash
# Override a specific image to use the latest (testing) channel
SANDBOX_IMAGE=ghcr.io/oro-ai/oro/sandbox:latest
```

When a new version is published, the ORO team verifies it on staging (`:latest`), then promotes to `:stable`. Watchtower on your validator detects the new `:stable` image and updates automatically.

Disable Auto-Updates [#disable-auto-updates]

Add the following to your `.env` file:

```bash
ORO_AUTO_UPDATE=false
```

When auto-updates are disabled, pull new images manually:

```bash
docker compose pull
docker compose --profile validator up -d
```