kurtosis-tech/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))

Common patterns

Wait for service readiness

plan.wait(
    service_name="my-service",
    recipe=GetHttpRequestRecipe(port_id="http", endpoint="/health"),
    field="code",
    assertion="==",
    target_value=200,
    timeout="60s",
)

Execute commands in a service

result = plan.exec(
    service_name="my-service",
    recipe=ExecRecipe(command=["cat", "/etc/hostname"]),
)
plan.verify(result["exit_code"], "==", 0)
plan.print("Hostname: {}".format(result["output"]))

Upload files

config_template = read_file("./templates/config.toml")
artifact = plan.render_templates(
    name="my-config",
    config={
        "config.toml": struct(
            template=config_template,
            data={"key": "value"},
        ),
    },
)

plan.add_service(
    name="my-service",
    config=ServiceConfig(
        image="my-image:latest",
        files={"/etc/myapp": artifact},
    ),
)

Import from other packages

dependency = import_module("github.com/org/other-package/lib.star")

def run(plan, args):
    dependency.some_function(plan)

Testing

Use a dry-run → execute → verify workflow:

# 1. Validate the plan without executing
kurtosis run --dry-run ./my-package

# 2. Run and check output
kurtosis run ./my-package

# 3. Inspect the created enclave
kurtosis enclave inspect <enclave-name>

# 4. Check service logs
kurtosis service logs <enclave-name> <service-name>

# 5. Shell into a service to verify state
kurtosis service shell <enclave-name> <service-name>

# 6. Clean up after testing
kurtosis clean -a

Common errors

| Error | Cause | Fix | |-------|-------|-----| | cannot use future reference in if | Using plan result in Python logic | Use plan.verify() or plan.assert() | | service not found | Service name typo or not yet created | Check plan.add_service() name matches | | port not found | Port ID mismatch | Ensure port_id in recipes matches ports dict key | | image pull failed | Image doesn't exist or no auth | Verify image tag, check docker pull manually | | kurtosis.yml not found | Running from wrong directory | Run from package root containing kurtosis.yml |