starlark-dev

Starlark Dev

Create, debug, and test Kurtosis Starlark packages.

Package structure

A minimal Kurtosis package needs two files:

my-package/
  kurtosis.yml    # Package metadata
  main.star       # Entry point

kurtosis.yml

name: github.com/your-org/my-package

main.star

def run(plan, args):
    plan.add_service(
        name="my-service",
        config=ServiceConfig(
            image="nginx:latest",
            ports={
                "http": PortSpec(number=80, transport_protocol="TCP"),
            },
        ),
    )

Running packages

# Run a local package
kurtosis run ./my-package

# Run with parameters
kurtosis run ./my-package '{"param1": "value1"}'

# Run a remote package from GitHub
kurtosis run github.com/ethpandaops/ethereum-package

# Run with a custom config file
kurtosis run github.com/ethpandaops/ethereum-package --args-file config.yaml

# Dry run (plan only, no execution)
kurtosis run ./my-package --dry-run

Execution model

Kurtosis Starlark executes in two phases:

1. Planning phase — Your code runs and builds a plan of actions. add_service(), exec(), etc. don't execute immediately — they return future references.
2. Execution phase — The plan is executed in order. Future references are resolved to actual values.

This means you cannot use the return value of plan.exec() in Python-level logic like if/else during the planning phase. Use plan.verify() or plan.assert() instead.

# WRONG: result is a future reference, not a real value during planning
result = plan.exec(service_name="my-service", recipe=ExecRecipe(command=["echo", "hello"]))
if result["output"] == "hello":  # This won't work as expected
    plan.print("matched")

# RIGHT: use plan.verify for conditional checks
result = plan.exec(service_name="my-service", recipe=ExecRecipe(command=["echo", "hello"]))
plan.verify(result["exit_code"], "==", 0)

Debugging with print

def run(plan, args):
    plan.print("Args received: {}".format(args))

    service = plan.add_service(
        name="my-service",
        config=ServiceConfig(image="nginx:latest"),
    )
    plan.print("Service IP: {}".format(service.ip_address))
    plan.print("Service hostname: {}".format(service.hostname))