Image Registry Configuration

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):

Default: docker.io
Configuration File (--config): Loads configuration from the specified path
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.

Programmatic Options: You explicitly pass the list of registries when initializing the runtime.
Default: docker.io (if you pass an empty list or nothing).

Python
Node.js

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!")

import { JsBoxlite, SimpleBox } from '@boxlite-ai/boxlite';

// Configure a runtime to search ghcr.io first, then docker.io
const runtime = new JsBoxlite({
  imageRegistries: ['ghcr.io', 'docker.io']
});

// Pass the custom runtime to the box constructor
const box = new SimpleBox({
  image: 'alpine',
  runtime: runtime
});

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.

Python
Node.js

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"))

import { readFileSync } from 'fs';
import { JsBoxlite } from '@boxlite-ai/boxlite';

function loadBoxliteRuntime(configPath: string): JsBoxlite {
  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
  return new JsBoxlite({
    imageRegistries: config.image_registries ?? [],
  });
}

// Use it
const runtime = loadBoxliteRuntime('./config.json');

Registry Resolution Order

To summarize the full resolution order for CLI usage:

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.

Try CLI --registry flags (highest priority)

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

Try registries from configuration file

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

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.

Private Registry Authentication

BoxLite uses an OCI-compliant image puller that respects the system’s Docker credential store. If your registry requires authentication, configure credentials through Docker’s standard mechanism.

Configure credentials

Use docker login to store credentials for your private registry:

# Log in to a private registry
docker login my.private.registry.com

# Log in to GitHub Container Registry
docker login ghcr.io -u YOUR_GITHUB_USERNAME

# Log in to AWS ECR (requires AWS CLI)
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

BoxLite reads credentials from ~/.docker/config.json at image pull time. No additional BoxLite-specific configuration is needed.

Credential helpers (e.g., docker-credential-osxkeychain on macOS, docker-credential-ecr-login for AWS) are supported. BoxLite invokes the same credential lookup chain that Docker uses.

Verify access

# Test that BoxLite can pull from your private registry
boxlite run my.private.registry.com/my-image:latest echo "Success"

Troubleshooting

Image not found (404)

Verify the image reference is correct and the image exists in the registry:

# Check with docker (or crane/skopeo) to confirm the image exists
docker manifest inspect my.registry.com/my-image:latest

Common causes:

Typo in the image name or tag
The image is in a different registry than expected (check your image_registries order)
The image was deleted or the tag was overwritten

Timeout pulling large images

Large images (multi-GB) can exceed default pull timeouts, especially on slow connections. BoxLite caches image layers, so subsequent pulls of the same or similar images are faster.Tips:

Use slim or alpine-based images where possible (e.g., python:slim instead of python:latest)
Pre-pull images before running time-sensitive workloads: boxlite pull my-image:latest
Use a local registry mirror or caching proxy to reduce network latency

TLS certificate errors

If your private registry uses a self-signed or corporate CA certificate:

# Add the CA certificate to the system trust store (macOS)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt

# Add the CA certificate to the system trust store (Ubuntu/Debian)
sudo cp ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

BoxLite uses the system’s TLS trust store for registry connections.

Authentication failed (401/403)

Verify your credentials are stored correctly:

# Check that credentials exist
cat ~/.docker/config.json

# Re-authenticate
docker login my.private.registry.com

If using a credential helper, ensure it is installed and working:

# Test the credential helper directly
echo "my.private.registry.com" | docker-credential-osxkeychain get

Getting Started

Tutorials

Guides

SDK Reference

Architecture

Resources

Development

How it Works

CLI Configuration

1. Configuration File

2. Using the Configuration File

3. Command Line Flags

SDK Configuration

Advanced: Loading Config in SDKs

Registry Resolution Order

Private Registry Authentication

Configure credentials

Verify access

Troubleshooting

​How it Works

​CLI Configuration

​1. Configuration File

​2. Using the Configuration File

​3. Command Line Flags

​SDK Configuration

​Advanced: Loading Config in SDKs

​Registry Resolution Order

​Private Registry Authentication

​Configure credentials

​Verify access

​Troubleshooting

How it Works

CLI Configuration

1. Configuration File

2. Using the Configuration File

3. Command Line Flags

SDK Configuration

Advanced: Loading Config in SDKs

Registry Resolution Order

Private Registry Authentication

Configure credentials

Verify access

Troubleshooting