Developer docs / AI Fabric tutorials

Bring your own image (Docker Hub / external registry)

  • Image DSL

AI Fabric's catalog images (fabric/torch, fabric/base) cover most GPU and Python work, but sometimes you need a specific base: a particular CUDA build from NGC, a community image from GHCR, or a plain python:3.12-slim from Docker Hub. AI Fabric lets you start from any public image and layer your dependencies on top, as you do with the catalog.

In this tutorial you'll see the two ways to choose an image (from_catalog(...) for AI Fabric's own images and from_registry(...) for anything on a public registry) and run a tiny function on a Docker Hub base. The key rule: the image's Python version must match your local Python, because AI Fabric ships your function with cloudpickle.

Before you start

Make sure the AI Fabric CLI is installed and authenticated (blade setup). No GPU is needed for this example. You'll also want your local Python to be 3.12, to match the image we pull (python:3.12-slim), because blade run ships your function with cloudpickle, which is not portable across Python minors.

Pull an image from a public registry

Create custom_image.py. from_registry(ref) pulls a public image from an allowlisted registry: Docker Hub official images (docker.io/library/…), docker.io/vllm/vllm-openai, nvcr.io/nvidia/… (NGC) and all of ghcr.io/…. Anything else is rejected at submission with 400 IMAGE_REGISTRY_FORBIDDEN, so your own Docker Hub org or a non-NVIDIA NGC namespace will not work. You must give a tag or digest (there's no implicit :latest), and then you extend it with the same .pip_install, .apt_install, .env, and .run_commands builders you'd use on a catalog image:

custom_image.py
import bladekit

app = bladekit.app("custom-image")

# from_registry pulls a public image from an ALLOWLISTED registry: Docker Hub
# official images (docker.io/library/...), docker.io/vllm/vllm-openai,
# nvcr.io/nvidia/... and ghcr.io/...; anything else is refused at submission
# with 400 IMAGE_REGISTRY_FORBIDDEN. Tag/digest required (no implicit ":latest");
# layer on top as usual. AI Fabric installs forge-runner + the SDK into it
# automatically. IMPORTANT: the image's Python must match your LOCAL Python
# (cloudpickle): python:3.12-slim (an official image) matches a 3.12 client.
image = (
    bladekit.Image.from_registry("python:3.12-slim")
    .pip_install("cowsay")
)

# For a GPU/CUDA base, use the catalog (already Python 3.12 + PyTorch):
#   image = bladekit.Image.from_catalog("fabric/torch")

Run a function on it

Now write an ordinary function and pass image=image to @app.function. The cowsay package only exists inside that Docker Hub image, so import it inside the function, where it runs in the container, not on your laptop:

Python
@app.function(image=image)
def greet(name: str) -> str:
    import cowsay
    return cowsay.get_output_string("cow", f"Hello {name}, from a Docker Hub image!")


@app.local_entrypoint()
def main():
    print(greet.remote("AI Fabric"))

Calling greet.remote("AI Fabric") ships the argument to a container built from your custom image, runs the function there, and returns the result. The first run builds the image (AI Fabric pulls python:3.12-slim and installs cowsay plus its own runner) and caches it, so later runs skip straight to execution.

Run it

Run the program with the AI Fabric CLI:

Terminal
blade run custom_image.py

You'll see a cow rendered by the cowsay package, proof that the function ran inside your Docker Hub image, not an AI Fabric catalog one:

Output
  ___________________________________
| Hello AI Fabric, from a Docker Hub image! |
  ===================================
                                   \
                                    \
                                      ^__^
                                      (oo)\_______
                                      (__)\       )\/\

Choosing a base for GPU work

For GPU or CUDA workloads, reach for the catalog first: bladekit.Image.from_catalog("fabric/torch") already ships CUDA, PyTorch, and Python 3.12, so there's nothing to assemble. If you need a registry image instead, make sure it's built on Python 3.12 to keep cloudpickle happy.

In short: from_catalog for AI Fabric's curated bases, from_registry for anything public, and the same DSL (.pip_install, .apt_install, .env, .run_commands) to layer on top of either one. Match the Python versions and you can run almost any container on the fleet. And if you already maintain a Dockerfile, you can hand it to AI Fabric as-is: see the Build your image from a Dockerfile tutorial.

Take it for a spin

Everything above in one file, ready to run.

custom_image.py
import bladekit

app = bladekit.app("custom-image")

# from_registry pulls a public image from an ALLOWLISTED registry: Docker Hub
# official images (docker.io/library/...), docker.io/vllm/vllm-openai,
# nvcr.io/nvidia/... and ghcr.io/...; anything else is refused at submission
# with 400 IMAGE_REGISTRY_FORBIDDEN. Tag/digest required (no implicit ":latest");
# layer on top as usual. AI Fabric installs forge-runner + the SDK into it
# automatically. IMPORTANT: the image's Python must match your LOCAL Python
# (cloudpickle): python:3.12-slim (an official image) matches a 3.12 client.
image = (
    bladekit.Image.from_registry("python:3.12-slim")
    .pip_install("cowsay")
)

# For a GPU/CUDA base, use the catalog (already Python 3.12 + PyTorch):
#   image = bladekit.Image.from_catalog("fabric/torch")


@app.function(image=image)
def greet(name: str) -> str:
    import cowsay
    return cowsay.get_output_string("cow", f"Hello {name}, from a Docker Hub image!")


@app.local_entrypoint()
def main():
    print(greet.remote("AI Fabric"))

Concepts used: Image build, Run

Contact the team

Loading the form…