Import a Docker image¶

Use sync_import_image or async_import_image to import a registry image. Each helper waits for completion and returns an image UUID for the sandbox factory.

An imported image can be the common starting point for several experiments. Work with a Session explains how to save changes, branch from a checkpoint, and return to an earlier state.

Configure the endpoint, token, and AI project as described in Connection sources. The registry must be reachable from the ConTree server. The example imports Alpine through a Docker Hub mirror and assigns the ConTree tag alpine:latest. Replace the registry URL with one available to your server.

Import and run a command¶

Save either program as import_image.py and run it with Python. Both programs wait for the import to finish, open a sandbox, and print Hello from an imported image!. The helpers use the same connection configuration as the sandbox factory.

Sync

"""Import a registry image and run a command in a sandbox."""

from contree_sdk import create_sandbox_session, sync_import_image


def main() -> None:
    image = sync_import_image("docker://mirror.gcr.io/library/alpine:latest", tag="alpine:latest")
    with create_sandbox_session(image=image) as sandbox:
        result = sandbox.run("echo", args=["Hello from an imported image!"])
        print(result.stdout)


main()

Async

import asyncio

from contree_sdk import create_sandbox_session, async_import_image


async def main() -> None:
    image = await async_import_image("docker://mirror.gcr.io/library/alpine:latest", tag="alpine:latest")
    async with create_sandbox_session(image=image) as sandbox:
        result = await sandbox.run("echo", args=["Hello from an imported image!"])
        print(result.stdout)


asyncio.run(main())

The helpers return only after a successful import. A failed import raises FailedOperationError. Assigning an existing ConTree tag moves it to the imported image.

The import supplies a filesystem. It does not start the registry image’s CMD or ENTRYPOINT, and it does not apply its WORKDIR. Select the command and working directory when running the sandbox.

Write a Docker URL¶

Pass the registry source as the first argument to sync_import_image or async_import_image. A full URL has this form:

docker://<registry>[:<port>]/<repository>:<tag>

Replace the angle-bracket placeholders; the port is optional. The repository includes its namespace, such as library/alpine or my-team/my-app.

Source URL	Meaning
`docker://docker.io/library/alpine:latest`	Official Alpine image on Docker Hub.
`docker://mirror.gcr.io/library/alpine:latest`	The mirror used in the example above.
`docker://ghcr.io/my-team/my-app:v1`	An organization’s image on GitHub Container Registry.
`docker://registry.example.com:5000/my-team/my-app:v1`	A registry with an explicit port. Replace the host and repository.

For Docker Hub official images, use the library/ namespace. Keep the docker:// prefix when writing a full source URL; do not replace it with https:// or a registry’s web page URL.

To select an exact registry manifest, replace :<tag> with @sha256:<64-hex-digit-digest>. Copy the complete digest from the registry. See the Docker transport reference for the underlying syntax.

String arguments also accept short names. The SDK expands alpine to docker://docker.io/library/alpine:latest, alpine:3.22 to docker://docker.io/library/alpine:3.22, and my-team/my-app:v1 to docker://docker.io/my-team/my-app:v1. A string that starts with docker:// is passed through unchanged, so use the complete form shown above.

The source tag selects the registry image to import. The helper’s tag= argument assigns a separate ConTree tag to the result; these names can differ. For private registries, pass credentials through ImageImportRegistry as described under Configuration below.

Reuse the imported image¶

Pass either of these references to create_sandbox_session(image=...):

Reference	Use
`tag:alpine:latest`	ConTree tag passed to the sandbox factory.
The returned image UUID	The specific imported filesystem, even if its tag later moves.

The factory does not import missing images; an unknown tag raises NotFoundError.

Dockerfile FROM has separate behavior: the builder imports a missing base image from its registry. See Build a Docker image.

Configuration¶

The import cache maps a registry source to its imported ConTree image UUID. A repeated call with the same source, requested ConTree tag, and credentials returns that UUID without another registry import. If tag= is supplied, the helper reapplies it to the cached image. The image itself stays on the ConTree server; the local cache contains only its UUID.

Records expire after one hour by default. Until then, a moved registry tag still returns the cached image. Pass no_cache=True to import it again and refresh the record. Keep cached images available on the server.

Records are stored in $XDG_CACHE_HOME/contree/images.sqlite3, or ~/.cache/contree/images.sqlite3 when XDG is unset. Connections and registry credentials have separate cache keys. Credentials are hashed, not stored in plaintext. Use cache_ttl= to change the lifetime or cache_dir= to choose another directory.

For several operations, initialize a client once and pass it through client=. The client is a shared dependency for import, build, and sandbox operations. See the complete Sync/Async example in Share one client. The caller closes a supplied client. Helpers close clients they create themselves.

Pass an ImageImportRegistry object instead of a string when the registry needs credentials. Pass store= to use your own Store for import results. See Image helpers for connection and retention parameters.

Continue with Build a Docker image to build a Docker image from a Dockerfile.