Cup: a read-only update checker for Docker images
🥤Docker container updates made easy
At a glance
- What is it?
- Cup scans your running containers, asks the registries whether newer tags exist, and reports the answer through a CLI or a web UI. It deliberately stops there, which is both its main selling point and its hardest limit.
- Who is it for?
- Adopt Cup if you want a small binary that answers one question (which of my images have newer tags) and you are willing to wire the result into your own cron job or webhook via cup check -r or the /api/v3/json endpoint. Do not adopt it if you need automatic pulling, restarting, or notification delivery; the README points those users at What's up Docker instead.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 55 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The rate limit problem Cup was built around
Checking whether a container image has a newer tag sounds trivial until you do it across dozens of containers. Every check is a registry API call, and Docker Hub throttles unauthenticated pull requests. The README states this plainly: not exhausting rate limits is 'the original reason I created Cup,' and the author notes the feature became more relevant after Docker Hub reduced pull limits for unauthenticated users. So the target user is someone self-hosting a stack of containers, running a periodic update check, and hitting throttling or slow sequential lookups. Cup is aimed at that person rather than at a platform team orchestrating fleets. The README also frames the project as intentionally small: the binary is described as 5.4 MB at the time of writing, against the 100+ MB Docker images some alternatives require. That size claim and the speed claim (3.7 seconds for 58 images on a Raspberry Pi 5, per the README) come from the author's own hardware and are not independently verified here.
How Cup finds your containers and queries registries
The mechanism visible in the material is a two-stage pipeline. First Cup enumerates containers, which is why the CLI command is cup check and why the project ships both a terminal interface and a web server exposing /api/v3/json. Second, it resolves each container's image reference against the registry that hosts it. The README lists Docker Hub, ghcr.io, Quay, lscr.io and Gitea or its derivatives as supported registries, which means the tool has to speak more than one registry API rather than assuming Docker Hub. The output is a comparison between the tag you are running and the tags the registry publishes. The README describes the project as taking 'full advantage of your CPU,' which points at concurrent registry queries rather than a sequential loop; that is the design decision that makes the Raspberry Pi timing plausible, though the number itself is the author's. The JSON output is offered for both the CLI and the web interface, and the README explicitly positions it as the integration surface: easy to parse, suitable for webhooks and dashboards. That is the whole architecture as documented. There is no agent, no sidecar watching the Docker socket for events, and no stored state described in the README.
Running the CLI and the web server
The concrete commands in the supplied material are limited, so treat this as the floor rather than a full setup guide. The README gives cup check -r as the way to run a check, and the Limitations section suggests running it from a cronjob for periodic checking. The web server exposes /api/v3/json, and the README suggests periodically requesting that URL as the alternative to the cron approach. Configuration keys, environment variables and install methods are not in the README; they live at cup.sergi0g.dev/docs, which is the first place to look before planning a deployment. The project also publishes a nightly release alongside tagged versions such as v3.5.1 and v3.5.0, so pinning to a tagged release rather than nightly is the safer default for anything you depend on. If you want the smallest possible footprint, the CLI plus a cron entry is the path the README itself sketches; the web UI is optional and adds a long-running process.
Cup will not update anything for you
The README's Limitations section is unusually direct: 'Cup cannot directly trigger your integrations.' There is no webhook delivery, no notification dispatch, no automatic pull, and no container restart. The author states the intent behind that: 'Cup was created to be simple. The data is there, and it is up to you to retrieve it.' So if your expectation is that a tool detects an update and then acts on it, Cup is the wrong tool by design, and the README says so and names What's up Docker as the alternative. A second limitation is coverage. The README describes the project as a work in progress that 'might not have as many features as other alternatives,' and the supported registry list, while broader than Docker Hub alone, is finite. A private registry not on that list, or a registry with non-standard authentication, is a case where Cup may simply not return an answer. Neither limitation is a bug; both are scope decisions, but they determine whether Cup fits your setup before you install it.
What's up Docker and the difference in approach
The README credits What's up Docker as the inspiration for Cup, and then draws the line between them. What's up Docker is presented as the tool to use if you want integrations triggered automatically; Cup is presented as the tool to use if you want the check itself to be fast, small and rate-limit friendly, with the acting left to you. That is a real architectural difference rather than a feature checklist gap. What's up Docker takes on the job of watching and notifying, which means a longer-running service with more surface area. Cup takes on the job of answering a question and getting out of the way, which means you own the glue: a cronjob around cup check -r, or a poller hitting /api/v3/json, plus whatever webhook or dashboard consumes the JSON. If you already have notification plumbing, Cup slots underneath it. If you do not, What's up Docker saves you from building it.
Licence and the cost of keeping Cup current
Cup is licensed AGPL-3.0. The practical consequence most self-hosters care about is the network clause: if you modify Cup and expose it to users over a network, the AGPL's source-availability terms can apply to your modified version. Running the unmodified web UI on your own machine is not the same situation, but the boundary depends on your deployment and is a question for your own legal review, not something this article can settle. On maintenance, the material shows an active release cadence with v3.5.0 and v3.5.1 close together and a nightly channel on top, so upgrades are frequent and the project is not dormant. That cuts both ways: you get fixes, and you get a moving target. Pinning to a tagged release and reading the release notes before bumping is the low-effort way to keep the CLI stable in a cron job. The registry APIs Cup depends on can change without any Cup release at all, which is the upgrade risk you cannot pin away.
Who should install Cup, and what to check first
Install Cup if the shape of the problem is 'I have many containers, I want to know which ones have newer tags, and I will handle the rest myself.' The JSON output from the CLI and from /api/v3/json is the integration point, and the README's own suggestion of a cronjob running cup check -r is the minimal viable setup. Skip it if you need detection and action in one tool, or if your registries are not covered. Before committing, confirm three things: that every registry you pull from appears in the supported list or behaves like one that does, that the AGPL-3.0 terms fit how you will run the server component, and that the docs at cup.sergi0g.dev cover the configuration keys you need, since the README does not. The author's speed figure is a claim from one Raspberry Pi 5, not a benchmark you can rely on; run cup check -r against your own container set and time it before you design a polling interval around it.
Editorial conclusion
Adopt Cup if you want a small binary that answers one question (which of my images have newer tags) and you are willing to wire the result into your own cron job or webhook via cup check -r or the /api/v3/json endpoint. Do not adopt it if you need automatic pulling, restarting, or notification delivery; the README points those users at What's up Docker instead. Before installing, verify the registry coverage you actually need against the supported list (Docker Hub, ghcr.io, Quay, lscr.io, Gitea and derivatives) and confirm the AGPL-3.0 terms are acceptable for how you intend to deploy the server component.
Community notes