Custom Docker Images

Custom Docker Images

Vellum Workflows are designed to run in a sandboxed environment. By default, the Vellum Python SDK uses a default Docker Image to run Workflows generated by the UI and pushed by the user from the CLI. However, sometimes you may want to use pre-existing logic from the rest of your repository, or some bespoke binaries that don’t translate well to the currently supported Vellum SDK languages. In these cases, you can use a custom Docker Image to run your Workflow.

Configuring a Custom Docker Image

To configure a custom Docker Image for a Vellum Workflow, you should first create a Dockerfile in the root of your Workflow module.

1FROM vellumai/python-workflow-runtime:latest
2
3# Install any additional dependencies you need
4# RUN pip install --upgrade pip && pip install numpy
5
6# Copy any custom code or utilities
7# COPY ./utils /custom/utils
8
9# Set environment variables if needed
10# ENV PYTHONPATH="${PYTHONPATH}:/custom"
11
12CMD ["vellum_start_server"]

There are few important things to note about this Dockerfile:

  • You must inherit from the vellumai/python-workflow-runtime image in order to run the Workflow on our infrastructure.
  • You have the flexibility to add any other dependencies you need to the image.
  • The vellum_start_server command is required to start the Vellum Server.

Building and Pushing Your Custom Image

Once you have your Dockerfile, follow these steps to build and push your image to Vellum:

1

Set your image name

$IMAGE_NAME="my-workflow-image-example"
2

Build the Docker image

$docker buildx build -f Dockerfile --platform=linux/amd64 -t $IMAGE_NAME:1.0.0 .
3

Push the image to Vellum

$vellum image push $IMAGE_NAME:1.0.0 --tag latest

Configuring Your Workflow to Use the Custom Image

Once you’ve pushed the image, you can configure your Vellum Workflow to use the custom Docker Image by adding the following to your pyproject.toml file:

1[[tool.vellum.workflows]]
2module = "my_workflow"
3container_image_name = "my-workflow-image-example"
4container_image_tag = "1.0.0"

This will tell Vellum to use the custom Docker Image when running the defined Workflow.

Using Custom Docker Images in the Workflow UI

After pushing your custom Docker image, you can select it in the Workflow Sandbox Settings. To do this:

  1. Open your Workflow in the Workflow Sandbox
  2. Click on the Settings button to open the Workflow Sandbox Settings modal
  3. In the “Container Image” section, you can select your custom Docker image from the dropdown

Workflow Sandbox Settings showing Container Image selection

Workflow Sandbox Settings showing Container Image selection

You can select from available system images or your own custom images. The dropdown allows you to choose the specific image tag as well.

Selecting a specific Container Image tag

Selecting a specific Container Image tag