Skip to main content
Version: 0.83.5


Kurtosis can be used to run a Starlark script or a runnable package in an enclave.

A single Starlark script can be ran with:

kurtosis run

Adding the --dry-run flag will print the changes without executing them.

A Kurtosis package on your local machine can be run with:

kurtosis run /path/to/package/on/your/machine

A Kurtosis package published to GitHub can be run like so:

kurtosis run

If you want to run a non-main branch, tag or commit use the following syntax kurtosis run


Package behaviour can be customized by passing in JSON-serialized arguments when calling kurtosis run.

For example, if your package's run function looks like this...

def run(plan, some_parameter, some_other_parameter="Default value"):

...then you can pass in values for some_parameter and some_other_parameter like so:

kurtosis run '{"some_parameter": 5, "some_other_parameter": "New value"}'

Kurtosis deserializes the JSON, with each key treated as a separate parameter passed to the run function in Starlark.

This is the equivalent to the following Starlark:

run(plan, some_parameter = 5, some_other_parameter = "New value")

By default, Kurtosis deserializes JSON objects (anything in {}) as dictionaries in Starlark. However, sometimes you need to pass a struct as a parameter instead.

To have Kurtosis deserialize a JSON object as a struct instead of a dictionary, simply add "_kurtosis_parser": "struct" to the object.

For example, this command...

kurtosis run '{"some_parameter": {"_kurtosis_parser": "struct", "some_property": "Property value"}}' equivalent to this Starlark:

run(plan, some_parameter = struct(some_property = "Property value"))

Extra Configuration

kurtosis run has additional flags that can further modify its behaviour:

  1. The --dry-run flag can be used to print the changes proposed by the script without executing them

  2. The --parallelism flag can be used to specify to what degree of parallelism certain commands can be run. For example: if the script contains an add_services instruction and is run with --parallelism 100, up to 100 services will be run at one time.

  3. The --enclave flag can be used to instruct Kurtosis to run the script inside the specified enclave or create a new enclave (with the given enclave identifier) if one does not exist. If this flag is not used, Kurtosis will create a new enclave with an auto-generated name, and run the script or package inside it.

  4. The --verbosity flag can be used to set the verbosity of the command output. The options include BRIEF, DETAILED, or EXECUTABLE. If unset, this flag defaults to BRIEF for a concise and explicit output. Use DETAILED to display the exhaustive list of arguments for each command. Meanwhile, EXECUTABLE will generate executable Starlark instructions.

  5. The --main-function-name flag can be used to set the name of Starlark function inside the package that kurtosis run will call. The default value is run, meaning Starlark will look for a function called run in the file defined by the --main-file flag (which defaults to Regardless of the function, Kurtosis expects the main function to have a parameter called plan into which Kurtosis will inject the Kurtosis plan.

    For example:

    To run the start_node function in a file, simple use:

    kurtosis run --main-function-name start_node

    Where start_node is a function defined in like so:

    # --------------- --------------------
    def start_node(plan, args):
    # your code
  6. The --main-file flag sets the main file in which Kurtosis looks for the main function defined via the --main-function-name flag. This can be thought of as the entrypoint file. This flag takes a filepath relative to the package's root, and defaults to For example, if your package is but your main file is located in subdirectories like, you should set this flag like --main-file src/internal/

    Example of using the --main-function-name flag

    For example, to run the start_node function in a file, simple use:

    kurtosis run --main-function-name start_node

    Where start_node is a function defined in like so:

    # code
    def start_node(plan,args):
    # your code
  7. The --production flag can be used to make sure services restart in case of failure (default behavior is not restart)

  8. The --no-connect flag can be used to disable user services port forwarding (default behavior is to forward the ports)

  9. The --experimental flag can be used to enable experimental or incubating features. Please reach out to Kurtosis team if you wish to try any of those.