Skip to main content

Docker Quickstart

In this quick start guide, we will write our first script ran from a Docker container.

Windmill natively supports Python, Typescript, Go, Bash or SQL. In some cases where your task requires a complex set of dependencies or is implemented in a non-supported language, Windmill allows running any Docker container through its Bash support.

As a pre-requisite, the host docker daemon needs to be mounted into the worker container. This is done through a simple volume mount: /var/run/docker.sock:/var/run/docker.sock.

script 1

Scripts are the basic building blocks in Windmill. They can be run and scheduled as standalone, chained together to create Flows or displayed with a personalized User Interface as Apps.

Scripts consist of 2 parts:

  • Code.
  • Settings: settings & metadata about the Script such as its path, summary, description, jsonschema of its inputs (inferred from its signature).

When stored in a code repository, those 2 parts are stored separately at <path>.ts and <path>.script.yaml.

Below is a simple example of a script built using Bash to run Docker containers from Windmill:

# shellcheck shell=bash
# Bash script that calls docker as a client to the host daemon
# See documentation:

COMMAND="/bin/echo Hello $msg"

# ensure that the image is up-to-date
docker pull $IMAGE
docker run --rm $IMAGE $COMMAND


To set-up Docker, see:


From the Home page of Windmill App, click +Script. This will take you to the first step of script creation: Metadata.


New script

As part of the settings menu, each script has metadata associated with it, enabling it to be defined and configured in depth.

  • Path is the Script's unique identifier that consist of the script's owner, and the script's name. The owner can be either a user, or a group (folder).
  • Summary (optional) is a short, human-readable summary of the Script. It will be displayed as a title across Windmill. If omitted, the UI will use the path by default.
  • Language of the script.
  • Description is where you can give instructions through the auto-generated UI to users on how to run your Script. It supports markdown.
  • Script kind: Action (by default), Trigger, Approval or Error Handler. This acts as a tag to filter appropriate scripts from the flow editor.

This menu also has additional settings, such as:

  • Concurrency limits enable defining concurrency limits for scripts and inline scripts within flows to prevent exceeding the API Limit of the targeted API.
  • Worker group tag to assign scripts to specific worker groups (such as nodes with GPU accelaration).
  • Cache to cache the results for each possible inputs for a given time.
  • Dedicated Workers to run the script on, to run the script at native speed. Only available on enterprise edition and for the Bun language.

Now click on the code editor on the left side.


Windmill provides an online editor to work on your Scripts. The left-side is the editor itself. The right-side previews the UI that Windmill will generate from the Script's signature - this will be visible to the users of the Script. You can easily preview that UI, provide input values, and test your script there.

Editor for Bash

As we picked Docker for this example, Windmill provided some Bash boilerplate. Let's take a look:

# shellcheck shell=bash
# Bash script that calls docker as a client to the host daemon
# See documentation:

COMMAND="/bin/echo Hello $msg"

# ensure that the image is up-to-date
docker pull $IMAGE
docker run --rm $IMAGE $COMMAND

msg is just a normal Bash variable. It can be used to pass arguments to the script. This syntax is the standard Bash one to assign default values to parameters.

docker run --rm <image> <command>

--rm is so that the container dispose itself after being executed. It helps unpollute the host.

The image is the docker image to run. It can be any image available on docker hub or any private registry. It can also be a local image.

The command is the command to run inside the container. It can be any command available in the image.

It is just a Bash script so it will behave exactly the same as a local command or if running this as an ssh command on the host. As a consequence, you can use any strategy to cache docker images or handle authentification.

Do not use the deamon mode -d otherwise the script will immediately return while the container continue to run in the background. However, in some cases, that might be what you want.

Like any Bash script, it will return the last line of the stdout. So be sure to print the the return value from your command if you'd like to use it as a result.

Instant Preview & Testing

Look at the UI preview on the right: it was updated to match the input signature. Run a test (Ctrl + Enter) to verify everything works.

Now let's go to the last step: the "Generated UI" settings.

Customize UI

From the Settings menu, the "Generated UI" tab lets you customize the script's arguments.

The UI is generated from the Script's main function signature, but you can add additional constraints here. For example, we could use the Customize property: add a regex by clicking on Pattern to make sure users are providing a name with only alphanumeric characters: ^[A-Za-z0-9]+$. Let's still allow numbers in case you are some tech billionaire's kid.

Advanced settings for Bash

We're done! Save your script. Note that Scripts are versioned in Windmill, and each script version is uniquely identified by a hash


Now let's look at what users of the script will do. Click on the Deploy button to load the script. You'll see the user input form we defined earlier.

Fill in the input field, then hit "Run". You should see a run view, as well as your logs. All script runs are also available in the Runs menu on the left.

Run Hello in Bash

You can also chose to run the script from the CLI with the pre-made Command-Line Interface call.

What's next?

This script is a minimal working example, but there's a few more steps that can be useful in a real-world use case:

Scripts are immutable and there is an hash for each deployment of a given script. Scripts are never overwritten and referring to a script by path is referring to the latest deployed hash at that path.

For each script, a UI is autogenerated from the jsonchema inferred from the script signature, and can be customized further as standalone or embedded into rich UIs using the App builder.

In addition to the UI, sync and async webhooks are generated for each deployment.