# 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-stdin
```

Or `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:v1
```

Multi-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](https://app.groundbox.dev/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](mailto:contact@groundbox.dev) 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 14
```

Space 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 repository
```

## API

`GET /registry`, `PUT /registry/namespace`, `GET /registry/repositories`, `GET /registry/repositories/{name}/tags`, `PATCH /registry/repositories/{name}` (visibility, retention) and the `DELETE`s. `{name}` is the whole name with its slash encoded: `acme%2Fapp`. See the [REST API](https://groundbox.dev/docs/api).
