Use your own image

Name the image. There is nothing to upload, build, or approve first.

Before you start

An API key exported as BOXLITE_API_KEY, and the REST URL as BOXLITE_REST_URL. See API keys.
pip install boxlite.

Start the box

import asyncio, os
from boxlite import ApiKeyCredential, Boxlite, BoxliteRestOptions, BoxOptions

rt = Boxlite.rest(BoxliteRestOptions(
    url=os.environ["BOXLITE_REST_URL"],
    credential=ApiKeyCredential(os.environ["BOXLITE_API_KEY"]),
))

async def main() -> None:
    box = await rt.create(BoxOptions(image="docker.io/library/alpine:3.20"), name="demo")
    print(box.id)

asyncio.run(main())

From the console it is New box, then type the reference. From the CLI:

boxlite run docker.io/library/alpine:3.20

Writing the reference

A short name means Docker Hub: alpine is docker.io/library/alpine:latest.

base, python, and node are BoxLite’s images, not Docker Hub’s. image="python" boots BoxLite’s Python box. Write docker.io/library/python:3.12-slim for Docker Hub’s.

What gets recorded

The first box to boot an image adds it to your catalog, and from then on that reference boots the same build — a box’s image reads back by digest, not by tag:

docker.io/library/alpine@sha256:c64c687cbea9…

The registry is not consulted again, so a tag someone moves upstream does not move for you. When you do want to move it, that is an alias. See what you have used:

images = await rt.images.list()

Recording happens when the box boots, not when create() returns — about 12 seconds later in a measured run. Reading the catalog immediately usually finds nothing. The catalog page has the polling pattern.

When a pull fails

Box state transition failed: Failed to pull image 'acme/api:1.4.0':
docker.io refused the pull (UNAUTHORIZED). The image is private or does
not exist, and no registry login of the organization covers it.

Three causes, in order of likelihood: the reference has a typo, the image is private and needs a registry login, or the tag does not exist.

A create that fails on its image still leaves the box behind, and you never received its id. Remove it by the name you passed to create().

Pin a build

Name the exact build production should boot.

Before you start

Start the box

Writing the reference

What gets recorded

When a pull fails

Next

Pin a build

Private images

​Before you start

​Start the box

​Writing the reference

​What gets recorded

​When a pull fails

​Next

Pin a build

Private images

Before you start

Start the box

Writing the reference

What gets recorded

When a pull fails

Next