Image registry
registry.groundbox.dev is a private container registry on the same machines as your CI runners and sandboxes. It speaks the OCI Distribution API, so Docker, BuildKit, crane, skopeo and Helm work with it as they are. You log in with the same API key, and storage is on the same bill.
Log in
Use an API key with the registry:push scope (registry:pull if it only pulls). The user name can be anything.
echo "$GROUNDBOX_API_KEY" | docker login registry.groundbox.dev -u groundbox --password-stdinOr groundbox registry login, which does the same with the key the CLI uses.
Push and pull
docker build -t registry.groundbox.dev/acme/app:v1 .
docker push registry.groundbox.dev/acme/app:v1
docker pull registry.groundbox.dev/acme/app:v1Multi-arch images (docker buildx build --platform linux/amd64,linux/arm64 --push), image indexes, attestations and OCI artifacts with a subject (signatures, SBOMs) are all kept, and the referrers API lists them.
Namespaces
Every team has one namespace: images are registry.groundbox.dev/<namespace>/<repo>. Your first push claims the namespace you push to, if nobody has it; or claim one first in Image registry or with groundbox registry namespace <name>. It can be changed only while the team has no images. Other teams can never read your images.
Public repositories
Repositories are private. Make one public in the dashboard or with groundbox registry visibility acme/app public: anyone can then pull it with no login. Only your team can push to it.
In CI on Groundbox
Jobs on Groundbox runners push and pull over the machine's own network, so pulls of your images in CI are fast and never leave the box. A job's VM may pull its own team's images without logging in (not a pull request from a fork). Sandboxes too.
jobs:
build:
runs-on: groundbox-4vcpu
steps:
- uses: actions/checkout@v4
- uses: docker/login-action@v3
with:
registry: registry.groundbox.dev
username: groundbox
password: ${{ secrets.GROUNDBOX_API_KEY }}
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
push: true
tags: registry.groundbox.dev/acme/app:${{ github.sha }}Save the key as the repository secret GROUNDBOX_API_KEY. It needs the registry:push scope.
Storage and price
- $20 plan: $0.05 per GB-month, by the second, up to 100 GB.
- Free plan: up to 1 GB, at no charge.
- Pushes and pulls are free, from anywhere.
- A layer shared by several of your images is stored and counted once.
A push past the quota is refused with denied: storage quota reached. Delete images or set retention rules to make room; write to us for a larger quota.
Retention
Per repository, about once an hour:
- Keep the newest N tags: older tags are deleted, with their images when nothing else points at them.
- Delete untagged images after N days: images no tag points at. The platform images of a tagged multi-arch image, and signatures of an image that is kept, are never deleted.
groundbox registry retention acme/app --keep-last 20 --untagged-days 14Space from deleted images is freed within the hour.
CLI
groundbox registry # namespace, storage, quota, price
groundbox registry ls # repositories
groundbox registry tags acme/app
groundbox registry rm acme/app:old-tag
groundbox registry rm acme/app --yes # the whole repositoryAPI
GET /registry, PUT /registry/namespace, GET /registry/repositories, GET /registry/repositories/{name}/tags, PATCH /registry/repositories/{name} (visibility, retention) and the DELETEs. {name} is the whole name with its slash encoded: acme%2Fapp. See the REST API.