Skip to main content

Custom (bring-your-own) images

When the curated catalog doesn't have what you need, a template service can point at any Docker image instead of a catalog entry. That image can come from Docker Hub, GitHub Container Registry, Amazon ECR, or any other registry — public or private.

Adding a custom image​

In the template builder, choose Custom image instead of a catalog service and give it:

  • An image repository without a tag — for example ghcr.io/acme/worker, mongo, or amazon/dynamodb-local. (The tag goes in its own field; an image:tag typed into the repository field is rejected.)
  • A tag — for example 7, latest, or 1.2.3.
  • An optional service name (defaults to the image's last path segment), used as the compose service name.

Custom images take the same config block as catalog services — env, command, ports, volumes, and resources. The loopback-only and named-volume conventions apply to custom services too, but the catalog's sensible defaults (default port, data path, auth env) do not — you configure those yourself.

Over the API, a custom service's source is { "kind": "custom", "image": "…" } rather than { "kind": "catalog", "catalogKey": "…" }. See the API reference for the full template schema.

Unverified images​

Catalog images are vetted by Slothbox; custom images are not. A custom image is badged unverified in the UI, and it's pulled directly from the registry you name. You're trusting the publisher of that image — review what you run, exactly as you would with docker run locally.

Services imported from a compose file are custom images too: even a stock postgres:16 imported that way is treated as an unverified custom image, not mapped back to the curated catalog.

Image pinning​

Catalog and custom images behave differently here:

  • Catalog images are pinned to a digest (sha256:…) when you save the template, so a bake gets the exact image the template was saved against. The friendly tag is still shown for readability; the digest is what gets baked. Pinning is best-effort: in the rare case the registry can't be reached at save time, the image is left on its tag.
  • Custom images are not digest-pinned. They are pulled by tag at each bake. The image baked into a given box image is fixed — every box launched from that bake runs the same bytes — but a rebake pulls whatever the tag points at then. There is no way to pin a custom image to a digest yet.

If reproducibility across rebakes matters, publish immutable tags from your CI (a version or commit SHA) and point the service at those, rather than reusing a moving tag like latest.

Next steps​

  • Private registries — give Slothbox the credentials to pull a custom image from a private registry.