kurtosis-tech Run Package
Execute Starlark scripts and packages with kurtosis run.
Basic usage
# Run a local package
kurtosis run ./my-package
# Run a local .star script
kurtosis run ./script.star
# Run a remote package from GitHub
kurtosis run github.com/ethpandaops/ethereum-package
# Run with inline args
kurtosis run github.com/ethpandaops/ethereum-package '{"participants": [{"el_type": "geth", "cl_type": "lighthouse"}]}'
# Run with args from a file (JSON or YAML)
kurtosis run github.com/ethpandaops/ethereum-package --args-file config.yaml
Named enclaves
# Run in a specific enclave (created if it doesn't exist)
kurtosis run --enclave my-testnet github.com/ethpandaops/ethereum-package
# Re-run in an existing enclave (adds to it)
kurtosis run --enclave my-testnet ./additional-services.star
Dry run
Preview what will execute without making changes:
kurtosis run --dry-run github.com/ethpandaops/ethereum-package --args-file config.yaml
Verbosity levels
# Default — concise description of what happens
kurtosis run ./my-package
# Brief — concise but explicit
kurtosis run -v brief ./my-package
# Detailed — all arguments for each instruction
kurtosis run -v detailed ./my-package
# Executable — generates copy-pasteable Starlark
kurtosis run -v executable ./my-package
# Output only — just the return value
kurtosis run -v output_only ./my-package
Image handling
# Default: only pull if image doesn't exist locally
kurtosis run ./my-package
# Always pull latest image tags
kurtosis run --image-download always ./my-package
Parallel execution
# Run instructions in parallel (as soon as dependencies resolve)
kurtosis run --parallel ./my-package
# Set parallelism level
kurtosis run --parallel --parallelism 8 ./my-package
Advanced options
# Production mode — services auto-restart on failure
kurtosis run -p ./my-package
# Custom entry point file
kurtosis run --main-file deploy.star ./my-package
# Custom main function
kurtosis run --main-function-name setup ./my-package
# Don't forward ports locally
kurtosis run --no-connect ./my-package
# Show dependency graph
kurtosis run --output-graph ./my-package
# List image and package dependencies
kurtosis run --dependencies ./my-package
# Pull all dependencies locally
kurtosis run --pull --dependencies ./my-package
# Skip enclave inspect output
kurtosis run --show-enclave-inspect=false ./my-package
Safe deployment workflow
Preview, execute, then verify:
# 1. Dry run — validate the plan without making changes
kurtosis run --dry-run --enclave my-testnet github.com/ethpandaops/ethereum-package --args-file config.yaml
# 2. Execute — run the package for real
kurtosis run --enclave my-testnet github.com/ethpandaops/ethereum-package --args-file config.yaml
# 3. Verify — confirm services are running correctly
kurtosis enclave inspect my-testnet
Debug mode
# Run with debug engine images
kurtosis --debug-mode run ./my-package
# Increase CLI log verbosity
kurtosis --cli-log-level debug run ./my-package