Skip to main content
This guide explains how to configure BoxLite to pull OCI container images from custom registries, such as a private enterprise registry, a third-party registry like ghcr.io or quay.io, or a local caching proxy.

​
How it Works

When you ask BoxLite to create a box from an image (e.g., image="alpine"), it needs to resolve this “unqualified” reference into a full image reference (e.g., docker.io/library/alpine:latest). By default, if no registries are configured, BoxLite uses docker.io (Docker Hub) as the implicit default. You can provide a list of custom registries. BoxLite will try to pull the image from each registry in the provided order. The first successful pull wins. If all registries fail, the operation returns an error.
Fully qualified image references (e.g., quay.io/prometheus/prometheus:v2.40.1) always bypass the search mechanism and are pulled directly.

​
CLI Configuration

The CLI layers configuration sources with the following priority (from lowest to highest):
  1. Default: docker.io
  2. Configuration File (--config): Loads configuration from the specified path
  3. CLI Flags (--registry): Prepended to registries from config file (highest priority)

​
1. Configuration File

Create a JSON configuration file with your registry preferences: 
{
  "image_registries": [
    "ghcr.io",
    "quay.io",
    "docker.io"
  ]
}
The image_registries field is optional. It contains a list of registries to search for unqualified image references.

​
2. Using the Configuration File

Use the --config flag to specify your configuration file: 
# Use a project-specific configuration
boxlite --config ./project-config.json run alpine
If you specify a config file with --config and the file does not exist or is invalid, the command will fail with an error.

​
3. Command Line Flags

You can use the global --registry flag with boxlite run or boxlite create. You can specify it multiple times. These flags are prepended to your configured list. This allows you to force a specific registry to be checked first for a single command without editing your config file. 
# Assume config.json contains ["ghcr.io", "docker.io"]

# This command will search:
# 1. my.private.registry.com (from flag)
# 2. ghcr.io (from config)
# 3. docker.io (from config)
boxlite --config ./config.json \
  run --registry my.private.registry.com \
  my-internal-app:latest

​
SDK Configuration

The SDKs are “pure” by design. They do not automatically load any configuration file. This ensures that your code’s behavior is deterministic and does not silently depend on the user’s local environment.
  1. Programmatic Options: You explicitly pass the list of registries when initializing the runtime.
  2. Default: docker.io (if you pass an empty list or nothing).
import boxlite

# Configure a runtime to search ghcr.io first, then docker.io
options = boxlite.Options(
    image_registries=["ghcr.io", "docker.io"]
)
runtime = boxlite.Boxlite(options)

# When creating a box, 'alpine' will be tried as:
# 1. ghcr.io/library/alpine
# 2. docker.io/library/alpine
async with boxlite.SimpleBox(image="alpine", runtime=runtime) as box:
    await box.exec(["echo", "Hello!"])

​
Advanced: Loading Config in SDKs

If you want your SDK application to respect a configuration file, you can manually load it. This puts the control in your hands. 
import boxlite
import json
from pathlib import Path

def load_boxlite_options(config_path: str):
    """Load BoxLite options from a configuration file."""
    with open(config_path) as f:
        config = json.load(f)

    return boxlite.Options(
        image_registries=config.get("image_registries", [])
    )

# Use it
runtime = boxlite.Boxlite(load_boxlite_options("./config.json"))

​
Registry Resolution Order

To summarize the full resolution order for CLI usage:
1

Check if the image reference is fully qualified

If the image reference includes a registry domain (e.g., quay.io/prometheus/prometheus:v2.40.1), pull directly from that registry. Skip all other steps.
2

Try CLI --registry flags (highest priority)

If --registry flags were provided, try each one in order.
3

Try registries from configuration file

If a --config file was specified and it contains image_registries, try each one in order.
4

Fall back to docker.io

If no registries were configured, or all configured registries failed, try docker.io as the final fallback.
For SDK usage, only steps 1, 3 (programmatic registries), and 4 apply. There are no CLI flags.