DOCSEARCHbyAlgolia
Submit Docs

Kurtosis Documentation

website·Indexed 33 days ago

https://docs.kurtosis.com/

A distributed application development platform for creating isolated, ephemeral environments called enclaves. The platform utilizes Starlark for environment definitions and provides a multi-phase approach to service instantiation and execution, including a comprehensive API for the Kurtosis Engine and APIC.

Tokens
57.4K
Snippets
294
Records
492
Agent score
66%

What's inside Kurtosis

  1. Overview of Claude Code Skills for Kurtosis

    Claude Code skills are structured Markdown files (SKILL.md) located in the skills/ directory of the Kurtosis repository. They provide Claude with operational knowledge, step-by-step instructions, common flags, and troubleshooting tips for the Kurtosis CLI, Docker/Kubernetes backends, and Starlark development. Claude Code automatically discovers and indexes these files to reference them during conversations.

  2. Overview of Kurtosis logs aggregation and sinks

    Kurtosis includes a logs aggregator component (powered by Vector) that collects logs from services across enclaves. The aggregator is configured per cluster within the Kurtosis configuration file. Kurtosis uses 'sinks' to define the destination for exported logs. Because it uses Vector, Kurtosis supports all sinks compatible with Vector.

  3. Overview of Kurtosis Cloud infrastructure

    Kurtosis Cloud is a managed service that provisions a remote AWS EC2 instance to run the Kurtosis engine, the Kurtosis API controller, and enclave services within Docker. Service ports from the cloud instance are forwarded to the user's local machine. Users can manage enclaves via the cloud portal UI or the Kurtosis CLI.

  4. Overview of Kurtosis Reusable Environment Definitions

    Kurtosis provides a framework for defining environments that are reusable across local Development, ephemeral Testing (CI), and Production. Unlike traditional tools, Kurtosis environment definitions are written in Starlark to ensure they meet six critical properties for reuse:

    1. Composability: Ability to combine multiple environment definitions (e.g., combining a Postgres definition with an Elasticsearch definition).
    2. Decomposability: Ability to instantiate only a specific subset of a larger environment definition.
    3. Safety: Validation of the environment (e.g., port and IP matching, image availability) before instantiation to shift errors from runtime to validation time.
    4. Parameterizability: Support for parameters to keep definitions DRY (e.g., specifying the number of nodes).
    5. Pluggability of Data: Ability to configure different datasets across different environments while using the same definition.
    6. Portability: Ensuring definitions can be shared and reproduced consistently across different machines (e.g., reproducing a CI failure on a local dev machine).

  5. Overview of Kurtosis

    Kurtosis is a tool used for packaging and launching environments of containerized services. It allows developers to deploy environments where they want them and how they want them using one-liner commands.

  6. Overview of the Kurtosis distributed application development platform

    Kurtosis is a distributed application development platform designed to make building distributed applications as simple as developing single-server apps. It operates on the philosophy that the 'environment'—rather than the individual container—is the fundamental unit of modern software, as services typically have implicit dependencies on other resources like volume data, secrets, certificates, and network rules.

    Kurtosis aims to provide a single abstraction layer for the entire software development lifecycle, including prototyping, testing, debugging, production deployment, and observability, reducing the friction and tooling gap between local development (e.g., Docker Compose) and production environments (e.g., Kubernetes/Helm).

  7. Inspect enclave flags via CLI

    The kurtosis enclave inspect CLI command provides detailed information about an enclave, including its configured flags.
    kurtosis enclave inspect <enclave-id>

  8. Configure a service using ServiceConfig

    The ServiceConfig object is used to define the container image and configuration for a service when it is added to a Kurtosis enclave (typically via the add_service function). It allows developers to specify whether a service should use a pre-existing image from a registry/local cache or be built from source using an ImageBuildSpec.

  9. Understand the full MEV network architecture

    A full MEV deployment via the ethereum-package consists of the following components running in Docker containers within a Kurtosis enclave:

    • Ethereum Nodes: Multiple nodes (e.g., 2) each paired with a mev-boost instance.
    • Flashbots Infrastructure: mev-relay suite (including mev-relay-api, mev-relay-housekeeper, and mev-relay-website) and mev-flood.
    • Data Stores: Redis and Postgres (required for mev-relay functionality).
    • Observability: Grafana and Prometheus for monitoring.
    • Utilities: Fork monitor, transaction spammer, testnet-verifier, and genesis data generators.

  10. Define Kurtosis Packages and User Services

    A Package is a directory containing a kurtosis.yml file along with necessary modules and static files. Within an enclave, a User Service is a container started from a user-specified image upon request to the Kurtosis engine.

  11. Manage services within an enclave using EnclaveContext

    Use the following EnclaveContext methods to retrieve information about services running in an enclave:

    • getServiceContext(serviceIdentifier): Returns a ServiceContext for a specific service identified by name, UUID, or short name.
    • getServiceContexts(serviceIdentifiers): Returns a map of ServiceName to ServiceContext for multiple requested services.
    • getServices(): Returns a map of ServiceName to ServiceUUID for all current services in the enclave.
    • getExistingAndHistoricalServiceIdentifiers(): Returns a ServiceIdentifiers object containing both active and deleted historical service identifiers.

  12. Interpret Starlark runner output with StarlarkRunResponseLine

    All Starlark run endpoints return a stream of StarlarkRunResponseLine objects. Each line in the stream is a union object that can be one of the following:

    • instruction: An instruction that is about to be executed.
    • instructionResult: The result of a successfully executed instruction.
    • error: An error thrown during the execution of the Starlark code.