# Kurtosis packages and launches multi-service stacks on Docker or Kubernetes > Kurtosis is a Go platform for defining backend stacks as reusable packages with parameters, file artefacts and wait conditions, then running them ephemerally on either the Docker engine or Kubernetes. It suits developers and CI systems that need throwaway environments, and it explicitly refuses production workloads. **kurtosis-tech/kurtosis** — A platform for packaging and launching blockchain infra. Think docker compose for blockchain - Repository: https://github.com/kurtosis-tech/kurtosis - Website: https://docs.kurtosistech.com/ - Stars: 557 · Forks: 99 - Language: Go - License: Apache-2.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/kurtosis-tech-kurtosis ## The problem of getting a colleague's stack running The opening question in the project description is the one that identifies the audience: have you ever tried to build on top of a colleague's work, or contribute to an open source project, and got stuck on the first steps of spinning up a stack to play with? That is the whole pitch. Kurtosis is described as handling the complexity of spinning up ephemeral dev or test stacks so you can focus on developing rather than configuring. The three components follow directly from that. There is a packaging system for distributing backend stack definitions, which can run on Docker or on Kubernetes. There is a runtime with a per-stack file management system for reproducibly initializing the state of your stack. And there is a set of tools for interacting with those stacks the way you interact with Docker or Kubernetes. The audience is developers who need a working multi-service environment quickly, and CI systems that need to create and destroy one repeatedly. The listed strengths hint at what the tool is actually for. Reusing the logic in your stack definitions for local dev, scheduled testing in CI, and ad hoc larger scale testing on Kubernetes clusters is one bullet. Giving other developers a way to spin up your application, and common variations of it, with one liners through the packaging and parameterization systems is another. Handling complex setup logic in a backend stack, like passing arbitrary data between services as they start up and enforcing arbitrary wait conditions, is the third. All three are about a stack with real dependencies between services, not a single container. ## The layer above Docker Compose and Helm The project is explicit about where it sits: Kurtosis operates at a level higher than Docker Compose or Helm, and produces stacks running on either of the underlying engines, the Docker engine or Kubernetes. Because of that extra layer of abstraction, four things become possible that the underlying tools do not give you. The first is a per-stack file management system that enables portable state initialization for dev or test stacks. The second is stack-level parameterizability, where users have a way beyond messing with environment variables to affect modifications in their stacks. The third is first-class plug-and-play composability, and the project says it is expected for users to import stack definitions into larger stacks, and that this experience is optimised for that. The fourth is the ability to have all of this running over either engine, at your election. The abstraction is not free, and the project says so in a note that is worth reading before you commit: it does not recommend using Kurtosis to deploy long term production environments at this moment, and any issues or Discord messages related to production usage will be closed. That is an unusual thing for a project to state plainly, and it tells you where the engineering effort has gone. The value is in reproducibility and composability of short lived environments, not in operating software. If you need a system that survives a deploy and stays up for months, this is the wrong category of tool and the project will not support you if you treat it as one. ## Running your first package Installation is documented at docs.kurtosis.com/install, and once the CLI is on your machine the quickest way to understand the whole thing is to run an existing package rather than write one. The project points at the Redis voting app in the awesome-kurtosis repository for exactly that purpose: ```bash kurtosis run github.com/kurtosis-tech/awesome-kurtosis/redis-voting-app ``` What you should see is a stack coming up and a URL printed. The documentation says to open the http link printed in the last line in your browser. The value of that command is what it demonstrates. A package is referenced by its GitHub path, so the definition travels with a repository rather than with a local file, and the runtime pulls it, wires the services together, handles the ordering and exposes a service over HTTP. There is no compose file to write, no local path to configure, and no per developer setup documentation to write. The awesome-kurtosis repository is the catalogue to browse after that, holding packages to try. The quickstart reference is where to learn how to write your own, and the main documentation covers how Kurtosis works. The repository also carries a short term roadmap linked from the description, which is where the direction of the product is written down rather than left to inference. ## How packages, parameters and wait conditions fit together The repository layout shows how much is going on under the CLI. There is an api/ directory, a cli/ directory, core/, engine/, enclave-manager/, connect-server/, container-engine-lib/, contexts-config-store/, grpc-file-transfer/, metrics-library/, name-generator/, path-compression/, cloud/, docs/, scripts/ and skills/. A few of those names carry the architecture. The engine is the layer that owns the execution environment, the enclave-manager deals with the sandboxed unit of work that Kurtosis calls an enclave, the container-engine-lib is the abstraction over the Docker engine and Kubernetes, and the connect-server with grpc-file-transfer handles how clients reach into a running enclave. The name enclave is a useful mental model. An enclave is a self contained stack with its own network and its own identity, which is what makes it reproducible and disposable. The contexts-config-store suggests that configuration is kept per context rather than globally, and the skills table lists context-manage and cluster-manage alongside service-manage, enclave-inspect and engine-manage, which describes a control surface where you can inspect what is running rather than only start it. Packages themselves are written in Starlark. Two of the skills are run-package for running Starlark packages and starlark-dev for developing them, which confirms the language and that the workflow has a real development loop. The combination of a packaging format, a runtime that honours it, and a language where package authors encode the tricky parts is the design. Encoding a wait condition or a data handoff in code rather than in YAML is the difference between a stack definition that works on one laptop and one that works on a CI runner at three in the morning. ## The Claude Code skills shipped in the repository One recent addition is worth a section of its own, because it changes who the tool is for. The repository includes Claude Code skills, which are structured prompts in a skills/ directory that give Claude operational knowledge about building, debugging, deploying and managing Kurtosis enclaves. Claude Code discovers them automatically when they are present in a project's skills/ directory. There are twenty one of them, and the list is effectively an index of what the tool does. There is run-package and starlark-dev for writing packages, docker-local-build and cli-local-build for the build path, docker-debug and k8s-debug-pods for the two engines, cluster-manage, engine-manage, service-manage, context-manage, enclave-inspect, files-inspect, port-forward, gateway and portal for the running stack, clean, dump and k8s-clean-cluster for teardown and inspection, import-compose for bringing in Docker Compose files, and grafloki for querying Grafana and Loki observability. Installing them is deliberately dull, and the four documented routes reflect different relationships to the project. If you are contributing to Kurtosis itself, the skills are already in the clone: ```bash git clone https://github.com/kurtosis-tech/kurtosis.git cd kurtosis ``` If you want them in another project, copy the directory over: ```bash cp -r /path/to/kurtosis/skills /path/to/your-project/skills ``` Or symlink it, which keeps the skills in step with the upstream repository without a copy step, and can be done for the whole directory or for a single skill: ```bash ln -s /path/to/kurtosis/skills /path/to/your-project/skills ``` The fourth route installs them globally for every project. The practical reading is that Kurtosis now has a machine readable description of its own operations, which means an assistant can drive enclaves without being told the command names. For teams already working with an agent in their terminal, that is a real change in the cost of using the platform, and it is also an argument for reading the skills directory even if you never run Claude Code, because it is the most compact description of the control surface in the project. ## Where Kurtosis is the wrong choice The clearest boundary is stated by the project itself: it does not recommend long term production environments, and production questions will be closed. That rules out using it as a deployment target. The second boundary is scope of definition. Docker Compose is a file format that many tools read, Helm is a packaging format for Kubernetes that many tools read, and Kurtosis is a package format with a runtime behind it. If you need a definition that a colleague without Kurtosis installed can run with a plain docker compose up, then a Kurtosis package is not that artefact, and you are writing it in Starlark for a runtime rather than in YAML for a parser. Third, the abstraction has a cost in debugging. When a service fails to come up, you are debugging through Kurtosis's own layers, the engine, the enclave, the connection server, on top of the container runtime underneath. The skills list is telling here, with dump for dumping enclave state for debugging and docker-debug and k8s-debug-pods sitting alongside it. Those tools exist because the debugging path is not simply kubectl logs. Fourth, and most simply, if your stack is a single container with no inter-service ordering, no data hand-off and no parameters, then a Dockerfile is less work. The parameterization and wait condition machinery only pays for itself once the stack has dependencies worth expressing. And a fifth point about adoption cost: the packages are written in Starlark, which is a Python dialect, so the language is not a barrier, but the model is. An organisation that has standardised on Helm charts and Docker Compose files has an investment in those formats, and Kurtosis asks a team to learn a packaging model that only works if the runtime is present on every machine and in CI. ## Conclusion Adopt Kurtosis if your team repeatedly spins up multi-service backend stacks for local development, scheduled CI testing or ad hoc larger scale testing, and you want one package definition reused across all three. Do not adopt it as a production deployment platform, since the project states plainly that long term production environments are not recommended and that issues about production use will be closed. Before you start, install it from the instructions at docs.kurtosis.com/install, run the redis voting app package to see the shape of a package, and read the quickstart reference for writing your own, keeping in mind that the language for package definitions is Starlark and the runtime targets either the Docker engine or Kubernetes at your election. ## FAQ ### How do I install Kurtosis and run my first stack? Install the CLI following the instructions at docs.kurtosis.com/install, then run `kurtosis run github.com/kurtosis-tech/awesome-kurtosis/redis-voting-app`. The runtime prints an http link on the last line, which you open in your browser to reach the running app. ### How is Kurtosis different from Docker Compose or Helm? Kurtosis operates at a level higher than both, producing stacks that run on either the Docker engine or Kubernetes. The extra layer brings a per-stack file management system, stack-level parameterization beyond environment variables, plug-and-play composability of stack definitions, and the choice of engine at run time. ### Can Kurtosis be used to deploy production environments? The project states that it does not recommend using Kurtosis to deploy long term production environments at this moment, and that any issues or Discord messages related to production usage will be closed. It is aimed at ephemeral dev and test stacks, including CI testing. ### What language are Kurtosis packages written in? Packages are written in Starlark. The skills shipped in the repository include run-package for running Starlark packages and starlark-dev for developing them, so there is a dedicated development workflow for the package format. ### What are the Claude Code skills in the Kurtosis repository? They are structured prompts in the skills/ directory that give Claude operational knowledge about Kurtosis, covering building, debugging, deploying and managing enclaves. There are twenty one, including run-package, docker-debug, k8s-debug-pods, port-forward, enclave-inspect, import-compose and grafloki, and they can be cloned, copied, symlinked or installed globally. ### What licence is Kurtosis released under and how often does it change? Kurtosis is Apache-2.0 licensed, with the terms in LICENSE.md. The repository is not archived and the last push was on 2026-10-16, with version 1.22.1 released the same day after 1.22.0 and 1.21.0 earlier in the week, so the release cadence is frequent and versioning follows semantic versioning. ## Sources - [kurtosis-tech/kurtosis on GitHub](https://github.com/kurtosis-tech/kurtosis) - [License: Apache-2.0](https://github.com/kurtosis-tech/kurtosis/blob/main/LICENSE) - [Project website](https://docs.kurtosistech.com/) - [README](https://github.com/kurtosis-tech/kurtosis/blob/main/README.md) - [Releases](https://github.com/kurtosis-tech/kurtosis/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kurtosis-tech-kurtosis