> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/reference/image-tags-and-arch · Doc index: https://docs.gatellm.io/en/llms.txt


# Image tags and architectures

The official image is published to `ghcr.io/gatellm-io/gatellm`. This chapter covers three things: which tags exist and when to use each; which CPU architectures the image supports and how they are selected on pull; and what those `-amd64` / `-arm64` suffixed tags on the GHCR package page are, and whether you should use them.

## Tag semantics and when to use them

| tag | meaning | when to use |
|------|--------|-------------|
| `vX.Y.Z` | immutable, corresponds to one formal release | **recommended for production** — reproducible and rollback-able |
| `latest` | floating, always points at the newest formal release | trialing, single-node, non-strict environments |
| `sha-<sha7>` | immutable, corresponds to a specific git commit (7-char short sha) | tracing a binary back to source, troubleshooting |

> ⚠️ Do **not** use `latest` in production: it is a floating tag, so a restart or scale-out can pull a different version, and a failure can neither be reproduced nor rolled back to a known target. Pin `vX.Y.Z`; for absolute immutability pin further to `@sha256:<digest>` (see below).

## Supported architectures

The official image is a **multi-arch OCI index**, so `docker pull` **auto-resolves the architecture for your host** with no extra flags:

| platform | coverage |
|----------|----------|
| `linux/amd64` | x86_64: Intel / AMD servers, Docker Desktop on Windows, Intel Mac |
| `linux/arm64` | aarch64: Kunpeng / Phytium / AWS Graviton / Ampere, Apple Silicon |

docker / containerd / Kubernetes / podman / nerdctl all select automatically from the OCI index's `platform` field, so the same `docker pull ghcr.io/gatellm-io/gatellm:latest` fetches arm64 on an ARM server and amd64 on an x86 server.

**Architectures not published**: armv7, ppc64le, s390x, loongarch64 (Loongson), etc. Pulling on these platforms reports:

```
no matching manifest for linux/<arch> in the manifest list entries
```

This is a hard limit — only `linux/amd64` and `linux/arm64` are published.

## When you need to pin an architecture explicitly

Usually you don't. But for cross-arch builds, image mirroring, or air-gapped environments, you can pin precisely two ways:

```bash
# Option 1: --platform picks the platform
docker pull --platform linux/arm64 ghcr.io/gatellm-io/gatellm:v0.2.0

# Option 2: @digest pins to an exact manifest (absolutely immutable)
docker pull ghcr.io/gatellm-io/gatellm@sha256:<digest>
```

> ⚠️ Don't pin `linux/amd64` on an ARM host: the pull succeeds (the manifest exists), but the container fails to start with `exec format error` — the binary is x86 instructions that the ARM CPU can't execute without an emulation layer like QEMU / Rosetta. Likewise, don't pin `linux/arm64` on an x86 host.

## Those `-amd64` / `-arm64` suffixed tags on the package page

Open the GHCR package page: releases up to `v0.2.0` additionally list `v0.2.0-amd64`, `v0.2.0-arm64`, `latest-amd64`, and similar suffixed tags.

**These are intermediate artifacts from the earlier build pipeline — ignore them.** Their origin: in earlier releases, the two architecture legs each pushed an addressable intermediate tag (`<tag>-<arch>`) on separate build machines for the merge step to reference. Their content is byte-identical to the same-platform slice of the corresponding multi-arch tag — `v0.2.0-arm64` is exactly the `linux/arm64` slice inside `v0.2.0`, nothing more.

Two key points:

1. **They can't be deleted.** Each intermediate tag shares a package version with the matching slice of the multi-arch tag; deleting it would also drop that architecture's reference from `v0.2.0` / `latest`, breaking pulls for that architecture.
2. **New releases no longer produce them.** The build pipeline now pushes intermediate images to a private staging repo, leaving only the final multi-arch tag in the public package.

So: just use `vX.Y.Z` / `latest` directly; to pin an architecture use `--platform` or `@digest` above, and ignore the suffixed tags.

## Offline / air-gapped transfer

`docker save` only exports the single image your local daemon resolved — the one architecture you pulled — losing the multi-arch index. Two correct approaches for offline environments:

```bash
# Option 1: pull per-platform first, then save (yields a single-arch tar)
docker pull --platform linux/arm64 ghcr.io/gatellm-io/gatellm:v0.2.0
docker save ghcr.io/gatellm-io/gatellm:v0.2.0 -o gatellm-arm64.tar

# Option 2: skopeo copy --all preserves the full index (for syncing to a private registry)
skopeo copy --all docker://ghcr.io/gatellm-io/gatellm:v0.2.0 docker://registry.example.com/gatellm:v0.2.0
```

## Verification commands

```bash
# See whether a tag is a multi-arch index (lists all platforms)
docker buildx imagetools inspect ghcr.io/gatellm-io/gatellm:latest

# See which architecture actually landed in your local daemon
docker image inspect gatellm --format '{{.Architecture}}'
```

## Related

- [Docker single-node quickstart](/en/quickstart/docker-single-node.md) — zero-config in 5 minutes, including a "supported architectures" section
- [Production checklist](/en/practices/production-checklist.md) — must-check before production, including "image version"
- [Licensing and authorization](/en/reference/licensing.md) — the image is a commercial build; unlicensed it runs as the free edition